#Media

MercuryCMS has a Media Library that allows you to manage images, videos, and audio to be used on the site. No files other than media files may be stored in the Media Library.

#Uploading and Managing Media

You can upload Media to MercuryCMS using the Media Library. You can drag and drop any files or folders from your desktop and then manage them just like they were local files.

You can use the Media Library to upload, delete, rename, and move Media as well as create Folders to organize them. You can hold Ctrl and click Media to select multiple and move or delete them all at once. To move Media to a parent Folder, drag them onto the name of the Folder in the breadcrumb at the top. You can also use shortcuts like pressing Del to delete Media or F2 to rename.

Note that unlike Assets, you can have multiple Media items and Folders with the same name in the same Folder, but this is not recommended.

#Organization

It is highly recommended to organize your Media files by which Page they're used on. For example, if you have a Page called "Contact Us" that has a header image and some social media icons, put all of those in a Media Folder called "Contact Us". This will make it much easier for people to find these images to change their alt text or replace them when maintaining the site.

Similarly, if you have a logo used by a Component called "Site Header", make a Media Folder called "Site Header" and put it there. Note that since all Media is accessed using its _id, you can move these files without breaking the page that uses it. So if you rename the "Contact Us" page to just "Contact", you can also rename the "Contact Us" Media Folder to "Contact" without breaking the links to the images within it.

Also, name your Media descriptively so it's easy to know which Media is used where. Media files with just numbers for names isn't helpful and will make it more difficult to maintain for others.

#Replacing Media

Unlike Assets, Media in the Media Library is not referenced by which Media Folder it's in when used on a page. For example, if you make an Asset called /contact-us/header-logo.png, you then put it on the Page using that path. If you move it, you will need to update every Page that uses that path. Also, you can replace that Asset by just deleting that file and making a new file in the /contact-us Asset Folder called header-logo.png.

Media does not work this way. If you upload an image called header-logo.png to the Media Library, it will create a Media item called header-logo. You can then use that on a page by referencing its _id, which in this example is 623e444d1943acc78b666788. You then realize you just uploaded it directly to the Media Library and didn't put it in a Media Folder, so you make one called "Contact Us" and move the Media into it. You then rename it "Header Logo". None of this changed its _id, so all Pages that reference it still work.

However, this means if you want to update Media, you cannot update it by deleting the Media and uploading a new one with the same name. If you want to do that without the _id changing so you don't have to update any Pages that use it, click the Media in the Media Library and click "Replace", then upload the new version you want to replace it. This will maintain the original _id.

#Media Properties

You can double-click any Media in the Media Library to edit it. This will allow you to change the name, set alt text, and provide a caption.

#Image Sizes

The benefit to uploading files as Media rather than as Assets, is that you get the benefit of automatic image optimization. MercuryCMS automatically converts images to .webp and generates different sizes that can be used dependent on the dimensions needed for the Page.

Size savings are significant using this method. For example, a 4000x3000 pixel .jpg test image is 6 MB, but when uploaded to the Media Library, it produces the following:

#Static Media Component

The simplest way to put an image on a Page, is to use the <static-media> Component. First, make sure you have the "Static Media" Component added to the Site by going to the Components screen. If it's not in the list, click "New From Library" and pick the "Static Media" Component.

Upload an image to the Media Library. Then go to the Page you want to use it on. Type static-media(media-id=) then put your cursor after the = sign and click "Insert Media ID". Pick the image you want to use and it will automatically insert it. It should now say something like static-media(media-id="623e444d1943acc78b666788"). Save the Page, and once the Build completes, you'll see the Page has the image on it.

You can now style the <img> however you want. You can give it width and height and use it anywhere you would use a normal <img> tag. You will most of the time want to specify a width or max-width and set height: auto to maintain aspect ratio.

If you look at the element itself, you'll see it was replaced with something like this:

<img
  src="/media/623e444d1943acc78b666788/original.webp"
  alt="A beautiful butterly"
  loading="lazy"
  decoding="async"
  height="3000"
  width="4000"
  class="static-media"
  data-cid-1
  >

To get the proper image size on the screen, you have two options. The easiest way to do it is to determine what the maximum width the image will be styled to on the Page and specify that alone. For example, if you are going to have a 150px wide thumbnail on the page, just use static-media(media-id="623e444d1943acc78b666788" size="150px"). This will tell the Static Media Component to only include the smallest size that is at least 150px.

The HTML will now look like this:

<img
  src="/media/624fa1a984114a954c410e2e/small.webp"
  alt="A beautiful butterly"
  loading="lazy"
  decoding="async"
  height="150"
  width="200"
  class="static-media"
  data-cid-1
  >

This will now save a lot of bandwidth, because it will not try to load a 4000x3000px image and scale it down to 150px wide. Note that since "150px" was specified, it chose to use 200px so it wouldn't have to scale up the 100px wide version.

You can also specify aliases such as size="medium" or size="720p". If no size is specified, or the size is larger than the largest sizes listed here, the original size will be used.

#Lazy Loading

In order to make it possible to put hundreds of images on a Page without affecting initial Page load time, images are loaded as the user scrolls through the Page. For any images you want to load immediately, use the above-the-fold attribute. Do not use this for footer images or get in the habit of putting this on all <static-media> components. Only use it for images that are visible without needing to scroll within a maximized desktop window or mobile browser. Example: static-media(media-id="624fa1a984114a954c410e2e" above-the-fold)

#Dynamic Media Ids

So far, we have only talked about hardcoding a specific Media ID into the <static-media> Component. What if you have a Blog Post Collection where users can upload Media using a Media Field? How do you get that on the page?

All Media Fields store the _id of the Media the user uploaded, so you can use them directly. For example, if you have Collection called "Blog Post" and it has a Media Field called "Featured Image", you would write static-media(media-id=blogPost.featuredImage).

#Media List and Media Entries

You can access all Media within the Media Library using the mediaList available within markup, style, data, etc. For a list of properties each Media Entry has, see Templating.

#Media Fields

You can allow users of MercuryCMS to upload Media when creating Collection Entries. For example, you could make a Collection called "Blog Post" that has a Media Field called "Featured Image". The Media Field will allow users to upload a new image file or select an existing image from the Media Library.

You can select which Folder you want the files to be uploaded to by writing out the path manually or by clicking "Browse" and picking a Folder using the Media Library. Note that if the folder doesn't exist when the user uploads the file, the path to the Folder will be automatically created.

The value that will be populated in this field will be the _id of the Media the user selected. To access a reference to the Media item itself, use the field name + "Ref" on the end. For example, if you create a Media Field called "Featured Image", you can use blogPost.featuredImage within markup or style to get the _id of the selected image. This is useful for when plugging it into a <static-media> Component.

If you want information about it, use blogPost.featuredImageRef. For example, you can access blogPost.featuredImageRef.name, blogPost.featuredImageRef.altText, blogPost.featuredImageRef.caption, etc.

For more information about Media Fields, see Collections.

#Direct Linking

While <static-media> works for using Media in Page markup, it's not useful within CSS, for example, as a background-image: url(). For that, you can use the mediaList or an invididual media object. For example, to get the 400px-wide url for an image, you could write any of these:

• background-image: url("{{ media.getImageUrl(400) }}")
• background-image: url("{{ mediaList.getById('624fa1a984114a954c410e2e').getImageUrl(400) }}")
• background-image: url("{{ blogPost.featuredImageRef.getImageUrl(400) }}")

You can also enter keywords like medium, large etc. as shown in Image Sizes.

Not all sizes are available depending on the original dimensions of the uploaded file. For example, a 500x200 image won't have an xxlarge.webp available.

To get an absolute URL that includes the site's FQDN and protocol (https://example.com/media/<mediaId>/small.webp), use media.getFullImageUrl() which takes the same arguments as getImageUrl().

#Video

Video files can also be uploaded to the Media Library, which works very similarly to images. Instead of generating multiple, different sized .webp files, it will generate multiple, different sized .webm files.

#Video Sizes

Here are the generated files for a 30 second 4K video:

This was a 16:9 video in landscape, but any aspect ratio or orientation is supported. The video will be resized to fit its longest dimension into each of these sizes without affecting the original aspect ratio.

MercuryCMS will also generate thumbnail images of the video as .webp files at all Image Sizes. These thumbnails will automatically be used by the <static-media> Component as the poster attribute and can be accessed using media.getImageUrl() just as with image Media.

#Video Direct Linking

To access a video Media URL directly, use media.getVideoUrl() and pass in the maximum width you want. You can also use any of the keywords from Video Sizes. For example, media.getVideoUrl(700) and media.getVideoUrl('720p') would both return /media/6266bcce56f8b6186cd7db25/720p.webm for the video uploaded above.

To get an absolute URL that includes the site's FQDN and protocol (https://example.com/media/<mediaId>/480p.webm), use media.getFullVideoUrl() which takes the same arguments as getVideoUrl().

#Audio

Audio files can be uploaded to the Media Library which works very similarly to videos. Audio files are converted into multiple files for compatibility.

#Audio Direct Linking

To access an audio Media URL directly, use media.getAudioUrl(). To get an Apple-compatible video, pass original_apple as the only argument. For example, media.getAudioByUrl() would return /media/6266bcce56f8b6186cd7db25/original.ogg, and media.getAudioByUrl('original_apple') would return /media/6266bcce56f8b6186cd7db25/original_apple.m4a.

To get an absolute URL that includes the site's FQDN and protocol (https://example.com/media/<mediaId>/original.ogg), use media.getFullAudioUrl() which takes the same arguments as getAudioUrl().