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.


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_items: 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 to the asset.

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.

Last modified on December 14, 2017