Assets Fieldtype

Overview

The assets fieldtype is used to manage and relate files with your entries. From the fieldtype you can manage custom fields on the assets themselves (learn more about that in the assets guide), preview full size images or rich media files, and even set focal points for cropping.

Files are rearrangeable via drag-and-drop.

UI Modes

The list mode is shown above, while the grid mode is below. There are no functional differences, only visual ones. List mode is more compact – useful if you're not primarily managing images.

Data Structure

Data is stored as an array of image paths relative to the asset container. Each asset's full URL is generated dynamically on the frontend based on the image path and its container. This allows containers to be a bit more portable by avoiding fully hardcoded file paths.

If max_files is set to 1, a string will be saved instead of an array.

# Default YAML
gallery_images:
  - fresh-prince.jpg
  - dj-jazzy-jeff.jpg
  - uncle-carl.jpg
 
# With max_items: 1
hero_image: surf-boards.jpg

Templating

The Asset fieldtype uses augmentation to automatically relate the files with their Asset records, pull in custom and meta data, and resolve all image paths based on the container.

By using a tag pair syntax, you'll be able to output variables for each asset:

{{ gallery_images }}
    <img src="{{ url }}" alt="{{ alt }}" />
{{ /gallery_images }}
 
{{ hero_image }}
    <img src="{{ url }}" alt="{{ alt }}" />
{{ /hero_image }}

<img src="/assets/fresh-prince.jpg" alt="Will Smith as the Fresh Prince" />
<img src="/assets/dj-jazzy-jeff.jpg" alt="Jeffrey Allen Townes as DJ Jazzy Jeff" />
<img src="/assets/uncle-carl.jpg" alt="Reginald VelJohnson as Carl Winslow" />
 
<img src="/assets/surf-boards.jpg" alt="3 colorful surf boards" />

The same tag pair syntax can be used regardless of your max_files setting.

If you have max_files: 1, you can also use a single tag syntax to directly use a variable inside the asset. Without a second tag part, the URL will be used.

{{ hero_image }}
{{ hero_image:url }}
{{ hero_image:alt }}

/assets/surf-boards.jpg
/assets/surf-boards.jpg
3 colorful surf boards

Variables

Inside an asset variable's tag pair you'll have access to the following variables.

Image Assets

Asset Field Data

All custom data set on the assets will also be available inside the asset tag loop.

{{ gallery_images }}
  <figure>
    <img src="{{ url }}" alt="{{ alt }}">
    <figcaption>{{ caption }}</figcaption>
  </figure>
{{ /gallery_images }}

Options