Assets

Assets are files managed by Statamic contained in specific directories. They can be images, videos, PDFs, giant text documents containing video game walk-throughs, or literally any other type of file. Each asset can have fields and content attached to them, just like entries.

Overview

Assets most often live in folders on your local server, in an Amazon S3 bucket, or other cloud storage service. Each of these defined locations is called a container..

Statamic scans the files in each container and caches meta information (like width and height for images) on them. This cache is used to speed up interactions and response times when working with them on the frontend of your site.

Asset Browser

The Control Panel’s asset browser gives you a great view on these files. You can file, sort, search, move, rename, preview, and — if working with images — even set focal crop points to make dynamically resized images significantly more useful.

Assets browser
The asset browser browsin' some assets.

Asset Fields

Asset fields are configured like a blueprint and attached to the container. Whenever you edit an asset in the Control Panel, you’ll see the fields from the configured blueprint.

This data is stored in the asset’s meta data file.

The asset editor editing an image
The asset editor in editing an image.

Metadata

  • Each asset in a container has a corresponding yaml file located in a .meta subdirectory. For example, images/tree.jpg gets an images/.meta/tree.jpg.yaml cache file.
  • These files contain cached data, including but not limited to: image dimensions, file size, last modification dates, and so on.
  • These cache files can also contain user created data. The fields are defined by the asset container’s blueprint. Typically these are alt text, focal points, descriptions, and so on, but they could be anything you want at all.
  • You may version control these files along with the assets themselves. It’s up to you if you find that helpful.
size: 9151
last_modified: 1558533973
width: 216
height: 104
data:
  alt: 'A tree with a tire swing'
  focus: 54-54-1

Containers

Each container has its own settings, configurable permissions, and blueprint. One container might be a local filesystem with upload, download, rename, and move permissions enabled, and another could be a read-only remote S3 bucket or stock image service.

Containers can be created through the Control Panel and are defined as YAML files located in content/assets. Each container’s filename becomes its handle.

# content/assets/assets.yaml
title: 'Assets'
disk: 'assets'

Each container implements a “disk”, also known as a Laravel Filesystem. This native Laravel feature groups a driver, URL, location, and visibility together. Statamic includes a local disk on fresh installs. You can modify or delete it, but many sites can simply use it as is.

'disks' => [
    'assets' => [
        'driver' => 'local',
        'root' => public_path('assets'),
        'url' => '/assets',
        'visibility' => 'public', // (more info about visibility below)
    ],
]

Filesystems are defined in config/filesystems.php They can point to the local filesystem, S3, or any Flysystem adapter.

Private Containers

Sometimes it’s handy to store assets that shouldn’t be publicly visible through a direct URL or browser.

If your asset container’s disk does not have a url property, Statamic will not output URLs.

Private containers should be located above webroot. If you leave the disk within the webroot, the files will still be accessible directly outside of Statamic if you know the file path.

/
|-- put-it-out-here
|-- public
|   `-- not-in-here

Make sure to also set the visibility to private.

Visibility

Your filesystem’s disk can have a visibility which is abstraction of file permissions. You can set it to public or private, which essentially controls whether they’re accessible or not.

Be sure to set 'visibility' => 'public', if you want to be able to see, interact with, and manipulate files in your container.

If you’re using a service based driver like Amazon S3, and you want the files to be accessibly by URL, make sure you set the visibility to public.

Blueprints

The default container Blueprint contains a single “alt text” field — just useful and simple enough to get you started.

You can customize the fields on the blueprint by visiting the container in the Control Panel and choosing “Edit Blueprint” in the options dropdown.

If you want to edit the blueprint file directly, you can do so in resources/blueprints/assets/{handle}.yaml.

Drivers

Statamic uses Flysystem and includes the core local driver. S3, SFTP, and other drivers can be installed with composer.

Flysystem is not limited to these three, however. There are adapters for many other storage systems. You can create a custom driver if you want to use one of these additional adapters in your Laravel application.

Frontend Templating

There are two main methods for working with Asset data on the frontend. The Assets Fieldtype, and the Assets Tag.

Assets Fieldtype

The Assets Fieldtype can be used in your content Blueprints to attach assets to your entries, taxonomy terms, globals, or user accounts. It can be used to create image galleries, video players, zip downloads, or anything else you can think of.

All of the data stored on your Assets will be available on the frontend without having to create any kind of duplication.

Example

If you had a slideshow field with a whole bunch of images selected, you can render them by looping through them.

<div class="slideshow">
    {{ slideshow }}
        <img src="{{ url }}" alt="{{ alt }}">
    {{ /slideshow }}
</div>

Learn more about the Assets Fieldtype.

Assets Tag

If you ever find yourself needing to loop over all of the assets in a container (or folder inside a container) instead of selecting them manually with the Assets Fieldtype, this is the way.

Example

{{ assets container="photoshoots" limit="10" sort="rating" }}
    <img src="{{ url }}" alt="{{ alt }}" />
{{ /assets }}

Learn more about the Assets Tag and what you can do with it.

Image Manipulation

Statamic uses the Glide library to dynamically resize, crop, and manipulate images. It’s really easy to use and has its own tag.

{{ glide:image width="120" height="500" filter="sepia" }}
Betterify this page on Github!