Images on landing pages

You can associate one or more images with a landing page and display them in your theme. The images are stored as an array on the landing page, so you can display all of them, just the first one, or a specific selection. This article is intended for developers and theme builders who work directly in Smarty templates, but store owners may also find the sections on uploading and alt text useful.

Upload Images to a Landing Page

1. Go to Landing Pages in your admin panel
2. Click Edit on the landing page you want to add images to
3. Use the image field to upload one or more images by dragging them in or clicking to select them from your computer
4. Write a short description for each image. The description is used as alt text and helps both screen readers and Google
5. Save the page

Display images in your theme

The landing page’s images are retrieved using `getImages()`, which returns an array of image objects. Each image has the `getSrc(width, height, type, format, quality)` method, which generates a URL for a scaled version of the image.

Display the first image (correct pattern)

<{$images = $landing_page->getImages()}>
<{if $images}>
  <{$image = $images[0]}>
  <img src="<{$image->getSrc(800, 400, 'fit')}>"
       alt="<{$image->getDescription()|escape}>">
<{/if}>

Show all images

<{foreach $landing_page->getImages() as $image}>
  <img src="<{$image->getSrc(800, 400, 'fit')}>"
       alt="<{$image->getDescription()|escape}>">
<{/foreach}>

Show only the first three images

<{foreach $landing_page->getImages() as $image name=img}>
  <{if $smarty.foreach.img.iteration <= 3}>
    <img src="<{$image->getSrc(600, 400, 'box')}>"
         alt="<{$image->getDescription()|escape}>">
  <{/if}>
<{/foreach}>

Display hero image with fixed crop and WebP

<{$images = $landing_page->getImages()}>
<{if $images}>
  <{$image = $images[0]}>
  <img src="<{$image->getSrc(1600, 700, 'box', 'webp')}>"
       alt="<{$image->getDescription()|escape}>"
       loading="eager">
<{/if}>

Parameters for getSrc()

• width and height: dimensions in pixels
• type: fit (default) keeps the entire image within the specified dimensions; box crops the image to the exact dimensions; and pad places the entire image on a white background within the exact dimensions without cropping
• format (optional): jpg, png, or webp. If you leave this blank, Shoporama will automatically choose the best format
• quality (optional): Shoporama always uses the store’s own quality setting, so you can omit this

Other useful methods for an image

• getDescription(): the image’s description; use as alt text
• getFilename(): the image’s original filename
• getWidth() and getHeight(): the image’s original dimensions in pixels
• getHtmlSize(width, height, type): returns the width and height attributes for the img tag, so the browser reserves space and the page doesn’t experience layout shifts
• getInline(width, height, type, format, quality): returns the image as base64 inline data, e.g., for preloads or CSS backgrounds without an extra request

Open Graph image for sharing

The Open Graph image is the image that appears when the landing page is shared on Facebook, LinkedIn, or similar platforms. It is a separate field and is retrieved using getOpenGraphImage(), which returns either an image object or `false`.

<{if $og = $landing_page->getOpenGraphImage()}>
  <meta property="og:image" content="<{$webshop->getUrl()|escape}><{$og->getSrc(1200, 630, 'box', 'jpg')}>">
<{/if}>

getSrc() returns a URL without a domain, so the store’s URL must be prepended; otherwise, Facebook cannot retrieve the image. Make sure no part of the image is cropped; use ` pad` instead of `box`.

Best Practice

• Upload the image at least as large as you want to display it. Shoporama scales down, not up
• Add a description to the image in the admin panel. This provides alt text and better SEO right out of the box
• Always wrap `getImages()` in an `<{if}>` check before accessing [0]. Otherwise, an empty array will cause an error
• Use getHtmlSize to set the width and height attributes so the page doesn’t jump when the images load
• Add loading="lazy" to images further down the page, but not to the first hero image

Frequently Asked Questions

I wrote $landing_page->getImage(), but the page breaks. Why?

Because the method doesn’t exist. On landing pages, it’s called getImages() (plural) and returns an array. If you only want to use one image, write $landing_page->getImages()[0] after checking that at least one image exists.

How many images can I upload to a landing page?

There’s no practical limit. But remember that every extra image is an extra file the customer has to download. On a typical landing page, 1 to 5 images are plenty. If you need to display a large gallery, consider lazy loading.

What file formats can I upload?

Shoporama supports JPG, PNG, GIF, and WebP. When the image is displayed in the shop, the system automatically converts it to the format and size specified in the theme, so you can safely upload your original high-quality image.

My image description isn’t showing up as alt text—why?

The description isn’t automatically included in the HTML. In your theme, you’ll need to retrieve it yourself using $image->getDescription()|escape and place it in the alt attribute of the img tag. Default themes like Delaware already do this for you.

Can I create a gallery or a lightbox?

Yes. Iterate through getImages() and create both a thumbnail and a full-size version of the same image using two separate getSrc() calls. Then combine them in a gallery script of your choice.

How do I get a full-page hero background from a landing page image?

For example, use `getSrc(2000, 800, 'box', 'webp') ` and set the image as the `background-image` via an inline style on a section. Choose WebP to keep the file size down on mobile.

How do I know if an Open Graph image has been uploaded?

Call $landing_page->getOpenGraphImage(). If it returns false, no separate Open Graph image has been set. Many people then choose to fall back to the first regular image using getImages()[0].

Will I be penalized in Google PageSpeed for large landing page images?

Yes, if you serve full-resolution images to mobile devices. Use `getSrc()` to request an appropriate size, set the `width` and `height` attributes on the `img` tag, and feel free to combine this with `srcset ` for responsiveness. See optimizing images for mobile.

Do I need to upload a new image for every size I want to display?

No. Upload a single high-resolution version—for example, 2000 pixels on the longest side—and Shoporama will generate all the smaller versions you request in the theme. The scaled images are automatically cached, so they’re only calculated the first time.

Need help? Contact us at support@shoporama.dk.