Template Tags

The tag pair is how you output Ansel images. Whether you are using the custom field tag within a Channel Entry tag pair, a Grid field tag pair, a Bloqs field tag pair, a Low Variables tag pair, or the stand alone tag pair, usage is almost identical across the tags. In fact, the only real difference is with the stand alone tag pair, which has just a few extra parameters available to it.

{exp:channel:entries channel="my_channel"}
    <!-- Number of images in field -->
    {my_ansel_field count="true"}

    <!-- Check if field has images -->
    {if "{my_ansel_field count='true'}" > 0}
        <!-- Do stuff if field has images -->
    {/if}

    <!-- Output images -->
    {my_ansel_field}
        {img:url}
        
        <!-- If using named crops output the entire <picture> tag -->
        {img:picture_tag}
    {/my_ansel_field}

    <!-- Output images from a grid field -->
    {grid_field}
        {grid_field:my_ansel_field}
            {img:url}
        {/grid_field:my_ansel_field}
    {/grid_field}
    
    <!-- Output images from a Relationship field -->
    {my_relationship_field}
        {my_ansel_field}
            {img:url}
        {/my_ansel_field}
        
        or
        
        {my_relationship_field:my_ansel_field}
            {img:url}
        {/my_relationship_field:my_ansel_field}
    {/my_relationship_field}
    
    <!-- Output images from nested Relationship fields across 2 entries -->
    {my_relationship_field}
        {my_relationship_field:child_relationship_field}
            {my_ansel_field}
                {img:url}
            {/my_ansel_field}
        {/my_relationship_field:child_relationship_field}
    {/my_relationship_field}

    <!-- Output images from a blocks field -->
    {blocks_field}
        {my_block}
            {my_ansel_block_field}
                {img:url}
            {/my_ansel_block_field}
        {/my_block}
    {/blocks_field}
{/exp:channel:entries}

<!-- Output images from a Low Variables Ansel field -->
{exp:low_variables:pair var="my_ansel_var"}
    {img:url:resize width="500"}
{/exp:low_variables:pair}

<!-- Output images with the stand alone tag -->
{exp:ansel:images content_id="102" field_id="33"}
    {if img:no_results}
        <!-- Do no results markup here -->
    {/if}
    {img:url:resize width="400"}
{/exp:ansel:images}

Tag Pair Parameters

image_id="104|105"
not_image_id="106|110"

site_id="2"
not_site_id="1"

file_id="2|3" // EE file id
not_file_id="18|27"

original_location_type="ee|assets" // Possible values: ee|assets|treasury
not_original_location_type="treasury|ee"

original_file_id="34|45"
not_original_file_id="45|56"

upload_location_type="assets|treasury" // Possible values: ee|assets|treasury
not_upload_location_type="ee|assets"

upload_location_id="34|45"
not_upload_location_id="45|56"

filename="my_file" // do not include extension
not_filename="foo"

extension="jpg"
not_extension="jpg"

original_extension="png"
not_original_extension="png"

filesize="182827"
filesize="< 182827"
filesize="> 182827"

original_filesize="182827"
original_filesize="< 182827"
original_filesize="> 182827"

width="300"
width="< 300"
width="> 300"

height="300"
height="< 300"
height="> 300"

title="my title|my other title"
not_title="foo|baz"

description="my description|my other description"
not_description="foo|baz"

member_id="23|24"
not_member_id="56|23"

position="2"
position="< 2"
position="> 2"

cover_only="true"
skip_cover="yes"
show_disabled="y"

namespace="my_namespace" // Access variables as {my_namespace:var}

limit="4"

offset="4"

order_by="date:desc|order:asc"

random="yes" // Overrides order_by parameter

cover_first="yes"

manipulations="true" // Include EE directory manipulations (requires extra queries)

host="https://cdn.domain.com/"

The following parameters are unique to the stand-alone image tag:

not_source_id="45|46"

content_id="34|36" or entry_id="34|36" // Usually the entry id, but could be low variables id
not_content_id="46|68" or not_entry_id="34|36"

content_type="channel|grid" // Possible values: channel|grid|blocks|low_variables
not_content_type="low_variables|channel"

field_id="23|26" or field_name="foobar"
not_field_id="45|56" or not_field_name="foobar"

row_id="32|33" // Grid or Blocks
not_row_id="444|745"

col_id="43|44" // Grid or Blocks
not_col_id="5|10"

Tag Pair Variables

Note all variable examples assume the default namespace of img. Use your custom namespace if you have set the namespace parameter.

These variables are available in the tag pair:

{img:id}
{img:site_id}
{img:content_id}
{img:field_id}
{img:content_type}
{img:row_id}
{img:col_id}
{img:file_id}
{img:original_file_id}
{img:upload_location_id}
{img:filename}
{img:original_filename}
{img:basename}
{img:original_basename}
{img:extension}
{img:original_extension}
{img:filesize}
{img:original_filesize}
{img:width}
{img:height}
{img:title}
{img:caption} <!-- This is the legacy variable, but {img:description} is preferred -->
{img:description} <!-- This is the new variable that replaces caption -->
{img:member_id}
{img:position}
{img:cover}
{img:upload_date}
{img:modify_date}
{img:path}
{img:original_path}
{img:url}
{img:original_url}
{img:thumbnail_path}
{img:thumbnail_url}
{img:index}
{img:count}
{img:total_results}
{img:host}
{img:description_field}
{img:credit_field}
{img:location_field}
{img:original_title_field} or {img:original_title}
{img:original_description_field} or {img:original_description}
{img:original_credit_field} or {img:original_credit}
{img:original_location_field} or {img:original_location}

The variables starting with "original" reference the value from the source file. When Ansel saves an image, it creates a new instance of that image in your file manager (wether it was cropped or not). Each instance of a file can have it's own description, caption, title etc. If you want to always reference the original description, regardless of which cropped version you're displaying in the template, you can use a conditional. For example:

{if img:original_description}
    {img:original_description}
{if:else}
    {img:description}
{/if}

When you have made manipulations available with the parameter manipulations="true", they will be available as follows:

{img:manipulation_name:path}
{img:manipulation_name:url}
{img:manipulation_name:width}
{img:manipulation_name:height}

No Results

If your tag pair has no results, you can use the {if img:no_results} conditional to output content.

On the Fly Cropping and Resizing

Ansel can crop and resize images on the fly. Doing so is very efficient because the cropped/resized image is cached after the first request for it is made. Any request for that cropped/resized image thereafter comes straight from the cache on disk.

Cropping/resizing is available to the {img:url} variable.

width="400"
height="100"
crop="true"
background="d34747"
force_jpg="true"
quality="80"
scale_up="true"
cache_time="86400" // Defaults to forever

{img:url:resize
    width="400"
    height="100"
    crop="true"
    background="d34747"
    force_jpg="true"
    quality="80"
    scale_up="true"
}

Get Total

Sometimes you would like to display the total number of images in a field. Ansel makes this really easy with a parameter on the custom field tag:

{exp:channel:entries channel="my_channel"}
    {my_ansel_field count="true"}
{/exp:channel:entries}

Picture Tag

`{img:picture_tag}`

Outputs a complete <picture> element. Only named crops with a Media Query value are included as <source> elements. The fallback <img> always uses the main crop ({img:url}).

Example output:

<picture>
  <source media="(min-width: 1200px)" srcset="https://example.com/uploads/ansel_saves/photo-42-desktop-1234567890.jpg">
  <source media="(min-width: 768px)"  srcset="https://example.com/uploads/ansel_saves/photo-42-tablet-1234567890.jpg">
  <source media="(max-width: 767px)"  srcset="https://example.com/uploads/ansel_saves/photo-42-mobile-1234567890.jpg">
  <img src="https://example.com/uploads/ansel_saves/photo-42-1234567890.jpg"
       width="1200" height="675" alt="Photo caption" loading="lazy">
</picture>

Tag Parameters

Parameter

Default

Description

picture_tag_loading

lazy

Value of the loading attribute on the <img> element

picture_tag_class

(none)

CSS class applied to the <picture> element

Example:

{ansel_field picture_tag_loading="eager" picture_tag_class="hero-image"}
    {img:picture_tag}
{/ansel_field}

Config Variable Substitution in Media Queries

Media query values in the field settings support {config_key} placeholders that are resolved at render time from EE's $config array. This avoids hard-coding breakpoints in the database and makes them easy to update site-wide.

In config/config.php:

$config['bp_small']  = '(max-width: 767px)';
$config['bp_medium'] = '(min-width: 768px)';
$config['bp_large']  = '(min-width: 1200px)';

In the field settings Media Query column:

{bp_large}
{bp_medium}
{bp_small}

At render time these resolve to their config values. Unrecognized placeholders are left as-is so typos are immediately visible in the rendered HTML.

Twig/Blade

If you're using Coilpack, Ansel supports Twig and Blade templates. All of the same parameters from the EE Template examples above are also available in Twig or Blade.

{exp:channel:entries
    channel="pages"
    dynamic="no"
}
    <h1>{title}</h1>
    
    {my_ansel_field}
        <img src="{img:url:resize width='600' height='200'}" />
        <!-- See list above for additional variables -->
    {/my_ansel_field}

{/exp:channel:entries}

{% for entry in exp.channel.entries({
    channel: 'pages',
    dynamic: 'no'
}) %}
    <h1>{{ entry.title }}</h1>

    {% for row in entry.my_ansel_field %}
        {{ row.url }} <!-- or -->
        <img src="{{ row.url.resize({width: 400, quality: 60}) }}" />
        
        {{ row.title }}
        {{ row.description }}
        {{ row.file_id }}
        <!-- See list above for additional variables -->
    {% endfor %}
    
{% else %}
    <span>No entries found</span>
{% endfor %}

Last updated 6 days ago