Templating With Ansel 1.x for Craft

# Image Criteria Model

Working with Ansel in the Craft Twig environment will be very familiar to any users of Craft. Whether you’re using something like entry.myAnselField or craft.ansel.images you’re going to be using the Image Criteria Model which is very similar to Craft’s Element Criteria Model in every meaningful way.

{% for image in craft.ansel.images %}
    <img src="{{ image.asset.url }}" alt="{{ image.title }}">
{% endfor %}

Like craft.entries, parameters can be chained, you can use things like first, last, limit and all those goodies

{% for image in entry.myAnselField.limit(1).skipCover(true) %}
    <img src="{{ image.asset.url }}" alt="{{ image.title }}">
{% endfor %}

# Criteria Model Parameters

{% set image = craft.ansel.images %}

{% set image = image.id('12,43') %} // Ansel image primary key
{% set image = image.notId('305,34') %}

{% set image = image.elementId('134,3456') %} // The owning element ID (such as an entry)
{% set image = image.notElementId('3453,56') %}

{% set image = image.fieldId('2,3') %}
{% set image = image.notFieldId('5,6') %}

{% set image = image.userId('7,8') %}
{% set image = image.notUserId('4,3') %}

{% set image = image.assetId('10,4565') %}
{% set image = image.notAssetId('3,8') %}

{% set image = image.originalAssetId('12,4568') %}
{% set image = image.notOriginalAssetId('4,18') %}

{% set image = image.width(300) %}
{% set image = image.width('< 300') %}
{% set image = image.width('> 300') %}

{% set image = image.height(300) %}
{% set image = image.height('< 300') %}
{% set image = image.height('> 300') %}

{% set image = image.title('my title,my other title') %}
{% set image = image.notTitle('foo,baz') %}

{% set image = image.caption('my caption,my other caption') %}
{% set image = image.notCaption('foo,baz') %}

{% set image = image.coverOnly(true) %}
{% set image = image.skipCover(true) %}
{% set image = image.showDisabled(true) %}

{% set image = image.position(2) %}
{% set image = image.position('< 2') %}
{% set image = image.position('> 2') %}

{% set image = image.limit(4) %}

{% set image = image.offset(4) %}

{% set image = image.order('position desc, fieldId asc') %}

{% set image = image.random(true) %} // Overrides order parameter

# Criteria Model Methods

{% set count = craft.ansel.images.width('> 300').count() %} {# Count matching images #}

{% set total = craft.ansel.images.height('> 300').total() %} {# Get total matching criteria regardless of limit/offset #}

{% set image = craft.ansel.images.first() %} {# Get the first image that matches criteria #}

{% set image = craft.ansel.images.last() %} {# Get the absolute last image that matches criteria regardless of limit/offset #}

{% set images = craft.ansel.images.find() %} {# Find instructs the model to run the query now #}
{# Normally the query will be run when needed when you iterate over images, etc. #}

# Image Model

Ultimately, when your looping through the Image Criteria Model, or getting the first or last result, you will be using the Image Model. The image model has the following properties you can access.

# Tag Pair Parameters

{% set image = entry.myImageField.random(true).first() %}

{{ image.id }} {# Integer #}

{{ image.elementId }} {# Integer #}
{% set element = image.element %} {# \Craft\ElementCriteriaModel #}

{{ image.fieldId }} {# Integer #}
{% set field = image.field %} {# \Craft\FieldModel #}

{{ image.userId }} {# Integer #}
{% set user = image.user %} {# \Craft\UserModel of the user who added the row to the field #}

{{ image.assetId }} {# Integer #}
{% set image = image.asset %} {# \Craft\AssetFileModel of the manipulated asset for this image #}

{{ image.highQualAssetId }} {# Integer #}
{% set highQualImage = image.highQualityAsset %} {# \Craft\AssetFileModel of the highest possible quality of the manipulated image #}

{{ image.thumbAssetId }} {# Integer #}
{% set thumbImage = image.thumbAsset %} {# \Craft\AssetFileModel of the highest possible quality of the manipulated image #}

{{ image.originalAssetId }} {# Integer #}
{% set originalImage = image.originalAsset %} {# \Craft\AssetFileModel of the original un-manipulated image #}

{{ image.width }} {# Integer #}

{{ image.height }} {# Integer #}

{{ image.title }} {# String #}

{{ image.caption }} {# String #}

{{ image.cover }} {# Boolean #}

{{ image.position }} {# Integer #}

{{ image.disabled }} {# Boolean #}

{{ image.dateCreated }} {# \Craft\DateTime #}

{{ image.dateUpdated }} {# \Craft\DateTime #}

# Examples

# A Field From an Entry

{% for entry in craft.entries.section('mySection').limit(2) %}
    <h1>{{ entry.title }}</h1>
    <div class="images">
        {% set images = entry.myImagesField.limit(2).coverFirst(true) %}

        {% if not images.count %}
            <div class="images__no-results">
                This gallery has no images at this time. Please check back later.
            </div>
        {% endif %}

        {% for image in entry.myImagesField.limit(2).coverFirst(true) %}
            <div class="images__image">
                <img src="{{ image.asset.url }}" alt="{{ image.title|default(entry.title) }}">
                <div class="images__image-caption">
                    {{ image.caption }}
                </div>
            </div>
        {% endfor %}
    </div>
{% endfor %}

# Resizing an Image on-the-fly

{% set image = craft.ansel.images.first() %}

{% set imageTransform = {
    mode: 'crop',
    width: 600,
    quality: 80,
    position: 'Center-Center'
} %}

<img src="{{ image.highQualityAsset.getUrl(imageTransform) }}" alt="{{ image.title }}">

# Ansel in a Matrix field

{% for entry in craft.entries.section('mySection').limit(2) %}
    <h1>{{ entry.title }}</h1>
    <div class="blocks">
        {% for block in entry.matrixField %}
            <h2 class="blocks__title">{{ block.galleryTitlie }}</h2>
            <div class="images">
            {% set images = block.myImagesField.limit(2).coverFirst(true) %}

            {% if not images.count %}
                <div class="images__no-results">
                    This gallery has no images at this time. Please check back later.
                </div>
            {% endif %}

            {% for image in entry.myImagesField.limit(2).coverFirst(true) %}
                <div class="images__image">
                    <img src="{{ image.asset.url }}" alt="{{ image.title|default(entry.title) }}">
                    <div class="images__image-caption">
                        {{ image.caption }}
                    </div>
                </div>
            {% endfor %}
        </div>
        {% endfor %}
    </div>
{% endfor %}