Field Tags

The following tags are available for your Assets fields within {exp:channel:entries} tag pairs.

Primary Tag Pair

The Primary Tag Pair will loop through each of your selected files, outputting whatever data you need from them.

{my_assets_field}
    <li><a href="{url}" alt="{alt_text}">{filename}</a></li>
{/my_assets_field}

Tag Parameters

The Primary Tag Pair supports the following parameters:

folder_id
The ID of the folder containing the files you wish to output. You may pass multiple IDs, delimited by pipes (‘|’).
url
Search for files by URL. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
server_path
Search for files by server path. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
subfolder
Search for files by subfolder. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
filename
Search for files by filename. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
extension
Search for files by extension. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
date_modified
Search for files by modified date (a Unix timestamp). You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘<’ , ‘>’ , ‘<=’ or ‘>=’ to match a range.
kind

Search for files by kind. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.

Posible values include:

  • access
  • audio
  • excel
  • flash
  • html
  • illustrator
  • image
  • pdf
  • photoshop
  • php
  • text
  • video
  • word
width
Search for images by width. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘<’ , ‘>’ , ‘<=’ or ‘>=’ to match a range.
height
Search for images by height. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘<’ , ‘>’ , ‘<=’ or ‘>=’ to match a range.
size
Search for files by size (in bytes). You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘<’ , ‘>’ , ‘<=’ or ‘>=’ to match a range.
file_id
Search for files by their ID in the exp_assets_files table. You may pass multiple values, delimited by pipes (‘|’).
title
Search for files by their Title metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
date
Search for files by their Date metadata value (a Unix timestamp). You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘<’ , ‘>’ , ‘<=’ or ‘>=’ to match a range.
alt_text
Search for files by their Alt Text metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
caption
Search for files by their Caption metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
author
Search for files by their Author/Credit/Producer metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
desc
Search for files by their Description metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
location
Search for files by their Location metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
keywords
Search for files by their Keywords metadata value. You may pass multiple values, delimited by pipes (‘|’) or double-ampersands (‘&&’). Prefix the value(s) with ‘=’ for exact match searching.
orderby
Order the files by a property or metadata value. Pair with the sort parameter to control the sort order.
sort

Sort the files in ascending or descending order (“asc” and “desc”, respectively), by the property/metadata specified in the orderby parameter.

If the orderby parameter was not set, sort="desc" will simply reverse the author-defined order of the files, and sort="random" will randomize the order of the files.

{my_assets_field orderby="title|kind|date" sort="asc|asc|desc"}
offset

Skip the first X files

{my_assets_field offset="{segment_4}" limit="1"}
limit

Limit the number of files to be returned

{my_assets_field limit="3"}
var_prefix

This parameter provides a way to avoid tag name conflicts by namespacing each of Assets’ variable tags. So for example, if you needed to access your current entry’s Title tag from within an Asset field’s tag pair, you could do this:

{my_assets_field var_prefix="file"}
  <a href="{file:url}">{title} - {file:title}</a>
{/my_assets_field}

Note: The {count} tag won’t be affected by this parameter.

backspace

Strip the last X characters from the tag output

{my_assets_field backspace="2"}{filename}, {/my_assets_field}

Variable Tags

The following variable tags are available within your primary tag pair:

{url}

The URL to the file.

{url:manipulation_name} is also available, for outputting the URL to an image manipulation.

{revved_url}
The revved URL to the file. The filename will be suffixed with a dot and the timestamp of when file was last modified. This will only work for files that are stored locally.
{server_path}

The server path to the file.

{server_path:manipulation_name} is also available, for outputting the server path to an image manipulation.

{subfolder}
The subfolder that the file lives in, if any.
{source_subfolder}
The value of the Subfolder setting on the file’s source, if there is one.
{folder_id}
Id of the folder containing the file.
{source_id}
Id of the source containing the file.
{filename}
The name of the file, sans-extension.
{extension}
The file extension.
{date_modified}
The date/time that the file was last modified. Supports the format parameter.
{kind}

The kind of file it is. Possible values are:

  • access
  • audio
  • excel
  • flash
  • html
  • illustrator
  • image
  • pdf
  • photoshop
  • php
  • text
  • video
  • word
{width}

The width of the image.

{width:manipulation_name} is also available, for outputting the width of an image manipulation.

{height}

The height of the image.

{height:manipulation_name} is also available, for outputting the height of an image manipulation.

{size}

The formatted size of the file (e.g. “20 KB”). You can also pass unformatted="yes" to get the raw file size in bytes.

{size:manipulation_name} is also available, for outputting the file size of an image manipulation.

{file_id}
The ID of the file (based on the id column in the exp_assets_files table).
{title}
The value of the file’s Title metadata field.
{date}
The value of the file’s Date metadata field. Supports the format parameter.
{alt_text}
The value of the file’s Alt Text metadata field.
{caption}
The value of the file’s Caption metadata field.
{author}
The value of the file’s Author/Credit/Producer metadata field.
{desc}
The value of the file’s Description metadata field.
{location}
The value of the file’s Location metadata field.
{total_files}
The total number of files being output.

Shortcut Tags

If you just want to get data about a single file within your Assets field, you can use a shortcut tag instead of the tag pair. They support the same parameters as the primary tag pair.

<h1>
  {if '{my_assets_field:title}'}
    {my_assets_field:title}
  {if:else}
    {my_assets_field:filename}
  {/if}
</h1>

The following shortcut tags are available:

  • {my_assets_field:url}
  • {my_assets_field:server_path}
  • {my_assets_field:subfolder}
  • {my_assets_field:source_subfolder}
  • {my_assets_field:filename}
  • {my_assets_field:extension}
  • {my_assets_field:date_modified}
  • {my_assets_field:kind}
  • {my_assets_field:width}
  • {my_assets_field:height}
  • {my_assets_field:size} – The formatted file size (e.g. “20 KB”)
  • {my_assets_field:size unformatted="yes"} – The file size in bytes
  • {my_assets_field:file_id}
  • {my_assets_field:title}
  • {my_assets_field:date}
  • {my_assets_field:alt_text}
  • {my_assets_field:caption}
  • {my_assets_field:author}
  • {my_assets_field:desc}
  • {my_assets_field:location}
  • {my_assets_field:total_files}

Image Manipulation Shortcut Tags

You can also access image manipulation properties using the following shortcut tags:

  • {my_assets_field:url:my_manipulation}
  • {my_assets_field:server_path:my_manipulation}
  • {my_assets_field:width:my_manipulation}
  • {my_assets_field:height:my_manipulation}
  • {my_assets_field:size:my_manipulation}