Formats

Retrieving Image Dimensions in Cascade

Cascade CMS exposes an image's width and height as integer pixel values — useful for setting HTML width and height attributes (which prevents Cumulative Layout Shift), responsive logic, or dynamic markup. Dimensions are accessible directly via the Cascade API or as child nodes when aggregating assets through an Index Block.

Using the Cascade API

There are two ways to access dimensions through the API depending on how you're referencing the image.

Via a structured data node

If your data definition includes a node pointing to an image file, use $currentPage.getStructuredDataNode() with the node's path to retrieve it. Because the node wraps the file asset, you need .asset.dimensions to reach the dimension values.

#set($image = $currentPage.getStructuredDataNode("group/image-node"))
$image.asset.dimensions.width
$image.asset.dimensions.height

Working inside a loop? — $currentPage.getStructuredDataNode() resolves paths from the page root. If you're already inside a loop over a group (for example, a #foreach iterating repeating rows), use .getChild() on the loop variable instead. See Variable Scope in Velocity for examples of navigating nested structured data.

Via $_.locateFile()

When you locate a file directly using $_.locateFile(), the returned object is the file asset itself — .asset is not needed, and dimensions are available directly on .dimensions.

#set($image = $_.locateFile("_images/example.webp", "${currentPageSiteName}"))
$image.dimensions.width
$image.dimensions.height

Using an Index Block

When aggregating images via an Index Block, width and height are available as child nodes on each system-file result.

Index Block setup required — for dimension nodes to be present in the output, the Index Block must be configured correctly:

  • Under Indexed Asset Content, select Regular Content
  • Under Indexed Asset Types, check Include Files

With those settings in place, the Index Block produces XML with a system-file entry per image, and each entry contains width and height child nodes:

<system-index-block name="all-images" type="folder">
  <system-file id="...">
    <name>example.png</name>
    <path>/_images/example.png</path>
    <link>site://Example Site/_images/example.png</link>
    <file-size>22868</file-size>
    <width>625</width>
    <height>181</height>
  </system-file>
</system-index-block>

Loop over the results and retrieve each image's dimensions using .getChild():

#set($images = $_XPathTool.selectNodes($contentRoot, "/system-index-block/system-file"))

#foreach($image in $images)
  $image.getChild("width").value
  $image.getChild("height").value
#end
↑