Images on landing pages

You can attach one or more images to a landing page and display them in your theme. The images are placed as an array on the landing page, so you can show all of them, just the first one or a specific section. This article is aimed at developers and theme makers working directly in Smarty templates, but store owners can also benefit from the sections on uploading and alt text.

Upload images to a landing page

1. Go to Landing pages in your admin
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 from your computer
4. Write a short description on each image. The description is used as alt text and helps both screen readers and Google
5. Save the page

Show images in your theme

Landing page images are retrieved with getImages(), which returns an array of image objects. Each image has a getSrc(width, height, type, format, quality) method that generates a URL to a scaled version of the image.

Show 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}>

Only show 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, WebP and high quality

<{$images = $landing_page->getImages()}> <{if $images}> <{$image = $images[0]}> <img src="<{$image->getSrc(1600, 700, 'box', 'webp', 85)}>>" 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
• format (optional): jpg, png or webp. If you set nothing, Shoporama will choose the best format itself
• Quality (optional): integer between 0 and 100. Typically 80 to 90 provides a good balance between size and sharpness

Other useful methods on an image

• getDescription(): image description, use as alt text
• getFilename(): the original filename of the image
• getWidth() and getHeight(): the original dimensions of the image in pixels
• getHtmlSize(width, height, type): returns the width and height attributes of the img tag so that the browser reserves space and the page does not layout-shift
• getInline(width, height, type, format, quality): returns the image as base64 inline data, e.g. for preloads or CSS backgrounds without extra request

Open Graph image for sharing

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

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

Best practice

• Upload the image in at least the size you want to display it in. Shoporama scales down, not up
• Put a description on the image in admin. Then you have alt text and better SEO out of the box
• Always wrap getImages() in an {if} check before accessing [0]. An empty array will otherwise go wrong
• Use getHtmlSize to set width and height attributes so the page doesn't jump when images load
• Add loading="lazy" on images further down the page, but not on the first hero image

Frequently asked questions

I have written $landing_page->getImage(), but the page breaks. Why is this happening?

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

How many images can I upload to a landing page?

There is no practical limit. But keep in mind that each additional image is an extra file for the customer to download. On a typical landing page, 1 to 5 images is plenty. If you need to display a large gallery, consider lazy loading.

What file formats can I upload?

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

My description on the image does not appear as alt text, why?

The description does not automatically come out in HTML, in your theme you have to get it yourself with $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 lightbox?

Yes, you can. Invert getImages() and create both a thumbnail and a large version of the same image with two different 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?

Use e.g. getSrc(2000, 800, 'box', 'webp', 80) and set the image as a background image via inline-style on a section. Compress heavily and select 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, a separate OG image has not been set. Many people then choose to fall back to the first regular image with getImages()[0].

Do I get penalized in Google PageSpeed for large landing page images?

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

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

No, you don't. Upload one 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 are only calculated the first time.

Do you need help? Contact us at support@shoporama.dk.