Media v2 fields

Media v2 fields offer upload of multiple medias 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 and other types of media. Want to migrate from the Media v1 to v2? Get in touch and we'll sort you out.

Media fields currently supports the following media types

  • JPG/JPEG, PNG, ICO, 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)

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

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

Uploaded medias 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 upload of multiple medias to the same field. If multiple medias are allowed, any number of medias can be uploaded.

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)

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 pointing the to uploaded media.

Use this as the value for referring to the media source over HTTP e.g. in the "src" attribute in image tags etc. The value of src is constructed to ensure that any new or replaced media file, even with the same filename, will reach your visitors' browsers straight away.

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 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 Cloudinary integration for resizing, cropping etc. See related articles below as well as the examples on this page.

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 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. Possible values are: "image", "video", "audio", "pdf", "text", "csv", "zip", "json" and "3d"

alt

For medias 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

Important: 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 Liquid's array filters such as first, last, sort, where etc.

Also: if you define a Media v2 field as repeatable, your 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 via Cloudinary to 200 by 200 pixels, keeping the aspect ratio

{% assign img = product.metafields.accentuate.multi_images | first %} 
<img src="{{ img.cloudinary_src | append: 'w_200,h_200' }}" alt="{{ img.alt }}"/>

Filtering uploaded medias by media type:

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

Note: Medias 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 performance of ACF's media delivery has been optimized for a balance of speed and quality, nothing beats not downloading images not needed at all. You should still consider only loading images when needed, aka "lazyloading". Google explains the concept here and you can find a popular 3rd-party library here

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us