Assets

Used to retrieve Assets data from either an Asset Fieldtype or directly from an Container. Your site's Assets are managed and stored independently of your pages and entries and have a joined relationship through their id. Learn more about Assets.

Learn by watching!

Check out the fundamentals screencast on Assets.

Usage

The most basic usage is to iterate over an array of asset IDs. The tag takes its second segment from the name of the variable you wish you connect to. For example, if you have an images field, you would use {{ assets:images }}.

Here’s an example of some Assets in use.

bacon_images:
  - /img/applewood-smoked.jpg
  - /img/canadian.jpg

{{ assets:bacon_images }}
  <img src="{{ url }}" alt="{{ alt }}" /> Size: {{ size }}
{{ /assets:bacon_images }}

<img src="/img/applewood-smoked.jpg" alt="Applewood" /> Size: 355kb
<img src="/img/canadian-bacon.jpg" alt="Canadian" /> Size: 125kb

Single Assets

If you have an asset field with max_files: 1 the data will be saved as a string. As one cannot iterate over a string, the tag will adjust accordingly without complaining.

hero_image: /img/negasonic-teenage-warhead.jpg

{{ assets:hero_image }}
  <img src="{{ url }}" />
{{ /assets:hero_image }}

<img src="/img/negasonic-teenage-warhead.jpg" />

Asset (singular) Tag

You may have noticed that “Assets” is plural. If you have an array of assets and only want the first or if it bothers you that a plural-powered Tag would return a single asset, we have you covered. We also support the singular word Asset for the explicit purpose of only ever accessing a single Asset.

hero_image: /img/quailman.jpg

{{ asset:hero_image }}
  <img src="{{ url }}" />
{{ /asset:hero_image }}

<img src="/assets/img/quailman.jpg" />

Retrieving assets from a container or folder

It may be desirable to loop over all the assets in a container or folder instead of needing to pick out assets manually using a field.

In this case, you may omit the second tagpart, and use parameters to drive the tag.

{{ assets container="photoshoots" }}
    <img src="{{ url }}" />
{{ /assets }}

Knowing the ID of the container isn’t always an option. It may be simpler to specify the path. (This corresponds to the path within a container.yaml).

{{ assets path="assets" }}
    <img src="{{ url }}" />
{{ /assets }}

Lastly, you may target a specific folder in a container, if you wish.

{{ assets path="assets" folder="img" }}
    <img src="{{ url }}" />
{{ /assets }}

Parameters

field tagpart	Not actually a parameter, but part of the tag. For example, `{{ assets:photos }}` where `photos` is the name of the field containing an array of asset IDs.
id\|container string	When retrieving assets directly from a container (not through a field), this is the ID of the container.
folder string	When retrieving assets directly from a container, this will let you target a specific folder.
recursive boolean false	When retrieving assets directly from a container, this determines whether to get assets recursively through subdirectories.
limit integer	Limit the total results.
offset integer	The result set will be offset by this many assets
sort string	Sort entries by field name (or `random`). You may pipe-separate multiple fields for sub-sorting and specify sort direction of each field using a colon. For example, `sort="size"` or `sort="size:asc\|title:desc"` to sort by size then by title.

Variables

url string	The URL of the asset, relative to webroot.
permalink string	The absolute URL of the asset, including domain.
title string	The title, if set.
path string	The relative path from the asset container.
basename string	The filename. No path, but with the extension. eg. `jedi.jpg`
filename string	The filename. No path, no extension. eg. `jedi`
extension string	The file extension. eg. `jpg`
size string	A human readable version of the filesize. It will be displayed in the most appropriate format. eg. `36b`, `125KB`, `20MB`, `1.8GB`
size_bytes string	The filesize, in bytes.
size_kilobytes string	The filesize, in kilobytes.
size_megabytes string	The filesize, in megabytes.
size_gigabytes string	The filesize, in gigabytes.
size_b string	The filesize, in bytes.
size_kb string	The filesize, in kilobytes.
size_mb string	The filesize, in megabytes.
size_gb string	The filesize, in gigabytes.
last_modified string	The time the file was last modified, as a string formatted by whats defined in your config. eg. `January 18th, 2015`
last_modified_timestamp string	The time the file was last modified, as a timestamp.
last_modified_instance string	The time the file was last modified, as a `Carbon` instance.
width integer	The width in pixels, if it's an image.
height integer	The height in pixels, if it's an image.