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-phil.jpg
 
# With max_files: 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.

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

@foreach ($gallery_images as $asset)
    <img src="{{ $asset->url }}" alt="{{ $asset->alt }}" />
@endforeach
 
{{-- Assuming $hero_image is max_files: 1 --}}
<img src="{{ $hero_image->url }}" alt="{{ $hero_image->alt }}" />

<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-phil.jpg" alt="James Avery as Uncle Phil" />
 
<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.

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

{{ $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

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

@foreach ($gallery_images as $image)
    <img src="{{ $image->url }}" alt="{{ $image->alt }}" />
 
    @if ($caption = $image->caption)
    <figcaption>{{ $caption }}</figcaption>
    @endif
@endforeach

Dynamic Folders

In addition to selecting which container and folder assets will be uploaded into, you may configure the field to have a dedicated subfolder based on an entry's value.

For example, you may want to place all the images for a blog post in its own directory.

type: assets
container: images
folder: blog
dynamic: slug

This would result in image.jpg being uploaded to path/to/images/blog/my-entry-slug/image.jpg.

You may target the entry's id, slug, or author values.

Options