Rendering Media

Info on rendering media items and imaging cropping

Templates (Views) can access items in the Media library to assist in displaying rich content like galleries.

In the following examples, we will be looking at rendering an Image.

Image is only one of the 'types' of Media in Umbraco. The same principles apply to all Media Types. The properties available to render will be different from Media Type to Media Type. For example, a File will not have a Width property.

Rendering a media item

A media item is not only a reference to a static file. Like content, it is a collection of fields, such as width, height, and file path. This means that accessing and rendering media in a Template is similar to rendering content.

Example 1: Accessing a Media Image IPublishedContent item based on the ID

An uploaded image in the Media library is based on the Media Type Image which has a number of standard properties:

• Name

• Width & Height

• Size

• Type (based on file extension)

• UmbracoFile (the path to the file or JSON data containing crop information)

These standard properties are pre-populated and set during the upload process. For example, this means that the width and height are calculated for you.

If you want to add further properties to use with your Media Item, edit the Image Media Type under Settings. In this example, we are going to retrieve an image from the Media section. Then we will render out an img tag using the URL of the media item and use the Name as the value for the alt attribute.

The Media item in the following sample will use a sample Guid (55240594-b265-4fc2-b1c1-feffc5cf9571). This example is not using Models Builder.

@{
    // The Umbraco Helper has a Media method that will retrieve a Media Item by Guid in the form of IPublishedContent. In this example, the Media Item has a Guid of 55240594-b265-4fc2-b1c1-feffc5cf9571

    var mediaItem = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571"));

    if (mediaItem != null)
    {
        // To get the URL for your media item, you use the Url method:
        var url = mediaItem.Url();
        // to read a property by alias
        var imageHeight = mediaItem.Value<int>("umbracoHeight");
        var imageWidth = mediaItem.Value<int>("umbracoWidth");
        var orientationCssClass = imageWidth > imageHeight ? "img-landscape" : "img-portrait";

        <img src="@url" alt="@mediaItem.Name" class="@orientationCssClass"/>
    }
}

But wait a second, Umbraco comes with Models Builder. This means that you can use strongly typed models for your media items if Models Builder is enabled (which it is by default).

Example 2: Accessing a Media Image ModelsBuilder item based on the ID

As with example one, we are accessing a MediaType image using the same Guid assumption.

@{
    // Since the Image Model generated by Modelsbuilder is a compatible type to IPublishedContent we can use the 'as' operator to convert it into the ModelsBuilder Umbraco.Cms.Web.Common.PublishedModels.Image class
    var mediaItemAsImage = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571")) as Image;
    if (mediaItemAsImage != null)
    {
        // you could add this as an extension method to the Umbraco.Cms.Web.Common.PublishedModels.Image class
        var orientationCssClass = mediaItemAsImage.UmbracoWidth > mediaItemAsImage.UmbracoHeight ? "img-landscape" : "img-portrait";

        <img src="@mediaItemAsImage.Url()" alt="@mediaItemAsImage.Name" class="@orientationCssClass"/>
    }
}

It is always worth having null-checks around your code when retrieving media in case the conversion fails or Media() returns null. This makes your code more robust.

Working with Video files

If you upload a video file (such as .mp4) to the Media library, Umbraco will store it as a Video Media Type by default. Unlike images, video files won’t include properties like umbracoWidth or umbracoHeight, but you can still retrieve the media item and render it using the <video> HTML tag.

Example: Rendering a Video Media item

@{
    var videoUrl = string.Empty;
    var videoMediaItem = Umbraco.Media(Guid.Parse("8c49c5d3-cb2a-48b2-87c9-7e2c1873e948"));

    if (videoMediaItem != null)
    {
        videoUrl = videoMediaItem?.Url();
    }
}
      
@if (!string.IsNullOrEmpty(videoUrl))
{
    <video width="640" height="360" controls>
        <source src="@videoUrl" type="video/mp4">
            Your browser does not support the video tag.
    </video>
}

The example above assumes that:

• You've uploaded an .mp4 file to the Media section.

• You want to include basic playback controls in the browser.

• You know the media item’s ID.

You can also add custom properties to your Video Media Type (for example: thumbnail, autoplay, caption) under Settings > Media Types.

Other Media Items such as File

Accessing other media items can be performed in the same way. The techniques are not limited to the Image type, but it is one of the most common use cases.

Image Cropper

The Image Cropper can be used with Image Media Types and is the default option for the umbracoFile property on an Image Media Type.

When working with the Image Cropper for an image the GetCropUrl extension method is used to retrieve cropped versions of the image. Details of the Image Cropper property editor and other examples of using it can be found in the Image Cropper article. The following is an example to help you get started with the Image Cropper.

Example of using Image Cropper

@{
    var mediaItemToCrop = Umbraco.Media(Guid.Parse("55240594-b265-4fc2-b1c1-feffc5cf9571"));
    if (mediaItemToCrop != null)
    {
        <img src="@Url.GetCropUrl(mediaItemToCrop, "square")" alt="@mediaItemToCrop.Name"/>
    }
}

This example assumes that you have set up a crop called square on your Image Cropper Data Type.

If you want the original, uncropped image, you can ignore the GetCropUrl extension method and use one of the previously discussed approaches as shown below.

<img src="@mediaItemToCrop.Url()" />

More information

• Media Picker
• Image Cropper
• Creating a Media Type