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.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.
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).
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.
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.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.@{
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()" />
Last modified 13d ago