Working With Images

Images

Images are an essential part of almost every website, from blogs to portfolios. Automad's template language provides handy methods for basic image processing like resizing and cropping. When using a single image or iterating a set of images, resizing options can simply be passed to a with statement or a foreach loop. Resized images are generated on the fly and cached, so that every size is only processed once.

Resizing Images

The following example iterates all JPG and PNG images of the current page and resizes them to fit into a box of 400 by 300 pixels. Since crop is set to true, the images are cropped in order to exactly fill the given size.

<@ foreach in '*.jpg, *.png' { width: 400, height: 300, crop: true } @>
  <# Code to be used for each image. #>
  <img
    src="@{ :fileResized }"
    alt="@{ :basename }"
    width="@{ :widthResized }"
    height="@{ :heightResized }"
  >
  <p>@{ :caption | markdown }</p>
<@ else @>
  <# Code to be used when the list of images is empty. #>
<@ end @>

Within the code block, several runtime variables can be used to access the properties of each image. While the :file variable represents the original file, :fileResized refers to the path of the resized and cached version. The :caption variable returns the caption that is stored along with the file.

Options

width Integer
The maximum width of the resized image.
height Integer
The maximum height of the resized image.
crop Boolean
Defines whether the image is cropped to exactly fit the given width and height. When set to false, the image is scaled to fit into the given size while keeping its aspect ratio. The default is false.

Supported image formats are JPG, PNG, GIF and WebP.

Single Images

In order to process a single image, for example an image that is selected using an image field in the dashboard, the with statement can be used. The optional else block is processed in case the image doesn't exist.

<@ with @{ imageLogo } { width: 200 } @>
  <img src="@{ :fileResized }" alt="@{ sitename }">
<@ else @>
  @{ sitename }
<@ end @>

As a shorthand, the img function generates a complete <img> tag for the first image that matches a given pattern:

<@ img { file: @{ imageLogo }, width: 200, class: 'logo' } @>

Preview Images in Pagelists

A common requirement is a preview image for each page in a pagelist. Using filters, it is possible to fall back to the first image that is found in the content of a page, in case no dedicated preview image is selected. The following example is based on the pagelist items of the Standard Lite theme:

<@ foreach in pagelist @>
  <a href="@{ url }">
    <# Reset the variable first, in case no image is found. #>
    <@ set { :pagelistImage: false } @>
    <@ set {
      :pagelistImage: @{
        imagePagelist |
        def (@{ +hero | findFirstImage }) |
        def (@{ +main | findFirstImage })
      }
    } @>
    <@ with @{ :pagelistImage } { width: 600 } @>
      <img src="@{ :fileResized }" alt="@{ title }">
    <@ end @>
    @{ title }
  </a>
<@ end @>

Learn more about the findFirstImage filter and how editors can work with images in the dashboard.

Recurisve Navigations Layout Settings
Images
Images play an essential role on the web and in any digital presence. Automad provides responsive images, image galleries, and slideshows as blocks that can be added to any block editor field. These blocks make it easy to display individual images with custom focal points and responsive aspect ratios, as well as manage and present image collections in versatile ways — from structured galleries to responsive slideshows.
findFirstImage
Finds the first img tag in a rendered HTML string and returns the src attribute. This function can be used to extract the first image form a block variable to be used separately in any other place like a teaser section of a page card in a pagelist.
img
Creates an image tag for the first image file matching the specified glob pattern. The image can also be cropped by defining a maximum width and height.
foreach
The foreach loop iterates collections and lists of files. Depending on the type of list, Automad provides different runtime variables within the code block of the loop to refer to the current item. The :i variable always contains the index of the current iteration.
with
The with statement processes a block of code within the context of a given page or file. When using the URL of a page or one of the keywords prev and next as argument, the context changes to that page. When using a file path, the related runtime variables can be used and images can be resized or cropped directly. In case there is no matching page or file, an optional else block is processed instead.