Accentuate Custom Fields
  • Welcome!
  • Introduction
    • Getting started with ACF
    • Field scopes
    • How to show fields in your storefront
  • Dashboard
    • Reference Manager
      • Creating a new reference within Reference Manager
    • Filter & Group
      • Filter editor
      • Filter usage
    • Activity log
    • App settings
  • Field Definitions
    • Fields & Sections
    • Deciding on a field type
    • ACF Field types
      • Text
      • Markdown text
      • HTML
      • Checkbox
      • Selection
      • Tags
      • Number
      • Date
      • Color
      • Media v1 (legacy)
      • Media v2
      • Custom Object (JSON)
      • Multi-language Text
      • Reference fields
      • References to Global fields
    • Shopify Field types
      • Shopify » Single line text
      • Shopify » Multi-line text
      • Shopify » Boolean
      • Shopify » Color
      • Shopify » Custom objects (JSON)
      • Shopify » URL
      • Shopify » Date
      • Shopify » Date and Time
      • Shopify » Integer
      • Shopify » Decimal
      • Shopify » Weight
      • Shopify » Volume
      • Shopify » Dimensions
      • Shopify » Reference fields
    • Automatic tagging
    • Large sets
    • Field contexts
    • Field context filters
    • Copy and paste fields
    • Change field name and type
    • Import existing fields
    • Linking multiple stores
  • The Editor
    • Using the editor
    • Promote fields to sidebar
    • Layouts
    • Hide from search
    • Repeatable fields
    • Version control
    • Update value on order creation
  • Bulk Import & Export
    • Export custom field values
    • Import custom field values
    • Metaobject export / import
  • METAOBJECTS
    • What are Metaobjects?
    • Metaobject Definitions
    • Metaobject instances / values
    • Displaying Metaobjects on your storefront
    • Metaobject export / import
  • THEME EXTENSIONS
    • SEO keywords
    • Sticky promo bar
    • Products promotion
  • Liquid Guides
    • Learning Liquid
    • Resize & crop images
    • Check for empty values
    • Access field definitions
    • Order notifications
    • Allow customers to change their field values
  • OTHER
    • Webhooks
    • API
      • Access to custom fields
      • Endpoints
  • Help
    • FAQ
      • Why are one of my products no longer showing in my reference field?
      • I have multiple products/variants with the same name
      • How do I make changes to my field values in bulk?
      • I added a new field definition but it is not showing in my storefront
      • How do I copy my field setup to another store?
      • My fields are still showing after I have deleted their field definition
      • Why are none of my fields showing in the editor?
      • My newly created object in Shopify is not available in ACF
      • Reference lists are empty?
      • Why am I seeing a "value cannot exceed 100,000 characters" error when saving?
      • Why can't I name my field "first", "last" or "size"?
    • Need help?
  • Product
    • Changelog
    • Feedback & Suggestions
Powered by GitBook
On this page
  • Media properties
  • Examples
  1. Field Definitions
  2. ACF Field types

Media v2

PreviousMedia v1 (legacy)NextCustom Object (JSON)

Last updated 10 months ago

Media v2 fields offer the upload of multiple media in a single field, which can be arranged in order and more easily managed in the editor. Each media also offers properties for easy access to structured information about media type, image dimensions, aspect ratio, ALT text, etc.

This is the recommended way to create fields for uploading images, videos or other types of media.

Media v2 fields support a variety of file types such as:

  • JPG/JPEG, PNG, ICO, TIF, WEBP, GIF and SVG images

  • PDF, CSV, TXT, ZIP and JSON files

  • AI, PS and EPS (Postscript) files

  • MP3, MP4, WEBM and MOV (Quicktime) files

  • GLB files (3D images used in Shopify)

  • Font files (WOFF, WOFF2, TTF and OTF)

When defining fields, you determine the set of allowed filetypes to be uploaded via the editor.

If you need a media type not currently available, get in touch and we'll add it for you.

Uploaded media are automatically stored in our highly secure cloud bucket (with full redundancy and daily backup). The corresponding link to the file is stored in the Metafield, ready to use in Liquid. Part of the field definition is whether or not the field supports the upload of multiple media to the same field. If multiple media are allowed, you can upload more than one media in the same field.

Media properties

The media information is stored as JSON objects with the following properties:

id

For internal ACF use only. This uniquely identifies the individual media.

scope

For internal ACF use only. This is the scope for which the media is uploaded (e.g. a product id when uploaded for a product)

key

For internal ACF use only. This is the uploaded media's filename appended to a combination of the scope and the media's id (e.g. which field in which product;

src

The URL points to the uploaded media. Use this as the value for referring to the media source over HTTPS e.g. in the "src" attribute in image tags etc. You can optionally append transformation options to this URL for resizing and cropping - please see Resize & crop images

original_src

This is basically the same as src, but the domain is here original.accentuate.io rather than cdn.accentuate.io, which provides access to your original (and unoptimized, see below) media. This should normally not be used for other purposes than redownloading the original media, since performance will not be as good as its src counterpart.

cloudinary_src

A special URL for ease of use of our previous integration with Cloudinary for resizing, cropping, etc. of images. This property will continue to be available and in working condition but we do offer new resizing options - see the .src property above.

filename

The name of the media, when it was uploaded to ACF (including the extension, but excluding any folders)

handle

The media's handle is a string version of the media's id. This is used when doing lookups using a Media Reference field

mime_type

The mime type of the uploaded media, identifying exactly which type of media is contained in the file. Example: "image/jpg", "video/mp4" etc.

media_type

Contains the general type of the media such as "image", "video", "audio", "pdf" etc.

media_inline

Contains the actual file content of an uploaded SVG file, if the option to store it inline was enabled at the time of upload.

alt

For media of media_type "image", an ALT text can be provided in the ACF editor and is made available via this property.

width

The width of the image in pixels.

height

The height of the image in pixels.

aspect_ratio

The aspect ratio ( width / height ) of the image, which tells the orientation of the image:

  • less than 1.0 is a portrait image

  • exactly 1.0 is a square image

  • greater than 1.0 is a landscape image

Examples

If you define a Media v2 field as repeatable, you will essentially get an array of arrays in the underlying Metafield value

Basic list of all uploaded images:

{% for image in product.metafields.accentuate.multi_images %}
  <img src="{{ image.src }}" alt="{{ image.alt }}"/>
{% endfor %}

Basic list of all uploaded images in a repeatable media v2 field:

{% for multi_images in product.metafields.accentuate.repeatable_multi_images %} 
  {% for image in multi_images %} 
    <img src="{{ image.src }}" alt="{{ image.alt }}"/>
  {% endfor %}
{% endfor %}

Resizing the first image to 200 pixels wide, keeping the aspect ratio:

{% assign img = product.metafields.accentuate.multi_images | first %} 
<img src="{{ img.src | append: '&transform=resize=200' }}" alt="{{ img.alt }}"/>

Filtering uploaded medias by media type:

{% assign doc_files = product.metafields.accentuate.doc_files | where: 'media_type', 'pdf' %}
{% for pdf in doc_files %} 
    <a href="{{ pdf.src }}">{{ pdf.filename }}</a> 
{% endfor %}

The underlying Metafield value will always be an iterable array. If just a single media is uploaded, the array will only have one entry. This allows for consistent use of such as first, last, sort, where, etc no matter how many media are uploaded.

Note: Media are served directly via world-class software services with very low network latency. ACF also employs performance optimization techniques similar to Shopify when fetching images via cdn.accentuate.io, including transforming images to WEBP format for supporting browsers. While the performance of ACF's media delivery has been optimized for a balance of speed and quality, you should still consider . ACF currently has a limit of ~50MB per single media upload. You will typically only reach this limit when uploading video files. Take care not to force your visitors to download assets of this size but consider using a streaming service for large video files (like YouTube, Vimeo, etc.)

Liquid's array filters
further optimizations