Skip to content

Latest commit

 

History

History
116 lines (83 loc) · 5.5 KB

index.md

File metadata and controls

116 lines (83 loc) · 5.5 KB
Raw
meta.Title meta.Description keywords versionFrom
Rendering Media in Umbraco
Info on rendering media items and imaging cropping
v8 version8 rendering media imagecropper
8.0.0

Rendering media

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 MediaTypes (however the actual properties available to render will be different, for example a File won't have a Width property).

Rendering a media item

A media item is not only a reference to a static file, but like content, it is a collection of fields, such as width, height and the path to the stored file. This means that accessing and rendering media in a template is very similar to rendering content.

Example 1: Accessing a Media Image IPublishedContent item based upon its Id

An uploaded image in the media library is based on the MediaType Image which has defined 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, eg the width and height are calculated for you.

If you want to add further custom properties, eg 'Photographer Credit' to use with your Media Item, edit the Image MediaType under settings. In this example we are going to retrieve an image from the Media section and render out an img tag using the URL of the media item and making use of the Name as the value for the alt attribute.

Assumption: We are going to assume that our media item has an ID of 1234, and that we are not using Models Builder.

@{
    // The Umbraco Helper has a Media method that will retrieve a Media Item by Id in the form of IPublishedContent, in this example the Media Item has a unique id of 1234:

    var mediaItem = Umbraco.Media(1234);
}
@if (mediaItem!=null)
{
    // To get the url for your media item, you use the Url property:
    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, if you are using Umbraco v7.4.0+ it now 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 upon its Id

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

@using ContentModels = Umbraco.Web.PublishedModels;
@{
    // Since the Image Model generated by Modelsbuilder is a compatible type to IPublishedContent we can use the 'as' operator to convert into the ModelsBuilder Umbraco.Web.PublishedModels.Image class
    var mediaItem = Umbraco.Media(1148) as ContentModels.Image;
}
@if (mediaItem!=null)
{
    // you could add this as an extension method to the Umbraco.Web.PublishedModels.Image class
    var orientationCssClass = mediaItem.UmbracoWidth > mediaItem.UmbracoHeight ? "img-landscape" : "img-portrait";

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

:::note It's 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. :::

Other Media Items such as File

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

Image Cropper

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 ImageCropper for an image the GetCropUrl extension method is used to retrieve, cropped, resized versions of the uploaded image. Details of the Image Cropper property editor and other examples of using it can be found here. The following example is a quick example to help you get started.

Example of using Image Cropper with the Models Builder strongly typed Image model

@using ContentModels = Umbraco.Web.PublishedModels;

@{
    // We can use the 'as' operator to convert between IPublishedContent and ModelsBuilder Umbraco.Web.PublishedModels.Image
    var mediaItem = Umbraco.Media(1234) as ContentModels.Image;
}
@if (mediaItem!=null)
{
    <img src="@mediaItem.GetCropUrl("myCropAlias")" alt="@mediaItem.Name" />
}

This example assumes that you have set up a crop called myCropAlias 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="@mediaItem.Url" />

More information