Displaying content from media libraries

Media libraries represent a data storage for your MVC application. They can store different types of audio, video, image, and document files. For a complete list of the file types supported by default, see Supported file types in Media libraries.

You can retrieve media library files in MVC applications by using the Kentico API methods from the CMS.MediaLibrary namespace.

Retrieving media library files

The following example demonstrates how to retrieve files from Kentico media libraries in MVC applications. The example requires a media library with the code name SampleMediaLibrary to work properly.

1. Open your MVC project in Visual Studio.
2. Create a view model class representing media files. Define properties for storing the media file values that you wish to use in your views.
3. Create a new controller class or edit an existing one.
4. Implement a GET action method to retrieve media files. The following example retrieves .jpg files from the SampleMediaLibrary media library.
5. Use the view model to pass media file data to your views.

using System.Collections.Generic;
using System.Linq;
using System.Web.Mvc;

using CMS.MediaLibrary;
using CMS.SiteProvider;

        /// <summary>
        /// Retrieves media files with the .jpg extension from the 'SampleMediaLibrary'.
        /// </summary>
        public ActionResult ShowMediaFiles()
        {
            // Gets an instance of the 'SampleMediaLibrary' media library for the current site
            MediaLibraryInfo mediaLibrary = MediaLibraryInfoProvider.GetMediaLibraryInfo("SampleMediaLibrary", SiteContext.CurrentSiteName);

            // Gets a collection of media files with the .jpg extension from the media library
            IEnumerable<MediaFileInfo> mediaLibraryFiles = MediaFileInfoProvider.GetMediaFiles()
                .WhereEquals("FileLibraryID", mediaLibrary.LibraryID)
                .WhereEquals("FileExtension", ".jpg");

            // Prepares a collection of view models containing required data of the media files
            IEnumerable<MediaFileViewModel> model = mediaLibraryFiles.Select(
                    mediaFile => new MediaFileViewModel
                    {
                        FileTitle = mediaFile.FileTitle,
                        DirectUrl = MediaLibraryHelper.GetDirectUrl(mediaFile),
                        PermanentUrl = MediaLibraryHelper.GetPermanentUrl(mediaFile)
                    }
            );

            // Passes the model to the view
            return View(model);
        }

Getting media library file URLs

To generate media file URLs for MediaFileInfo objects, call the following methods of the MediaLibraryHelper class (available in the CMS.MediaLibrary namespace):

• GetDirectUrl – returns a direct URL to the media file on the file system. For example: ~/Kentico/DancingGoat/media/Images/sample_image.jpg

• GetPermanentUrl – returns a permanent URL to the media file. For example: ~/getmedia/0140bccc-9d47-41ea-94a9-ca5d35b2964c/sample_image.jpg

  The GetPermanentUrl method generates URLs that have the following behavior:

  • Allow checking of media library permissions (see Assigning permissions to media libraries for more details)
  • Allow resizing based on constraints when calling the ImageUrl method in views.
  • Include a URL extension based on the site’s Settings -> URLs and SEO -> Files friendly URL extension setting (set an empty value for extensionless URLs)

The methods return relative URLs – you need to process the value using the ImageUrl or FileUrl extension method in your views to get the final media file URL for your website.

Displaying media library files

To display media library files on your MVC site, create views that work with the generated media file URLs. Get the final URLs by calling the ImageUrl or FileUrl extension methods available in the Kentico.Content.Web.Mvc namespace.

@model IEnumerable<MediaFileViewModel>

@using Kentico.Content.Web.Mvc
@using Kentico.Web.Mvc

<h2>Media library file listing</h2>

@foreach (MediaFileViewModel mediaFile in Model)
{
    @* Gets a permanent URL for the media file and limits the file's maximum side size to 400 px *@
    string url = Url.Kentico().ImageUrl(mediaFile.PermanentUrl, SizeConstraint.MaxWidthOrHeight(400));

    <img src="@url" alt="@mediaFile.FileTitle" />
}

When using permanent URLs, you can resize image files via the SizeConstraint parameter of the ImageUrl method. The following image size constraints are available:

• SizeConstraint.Empty – leaves the image as-is

• SizeConstraint.Height(100) – resizes the image to the specified height (maintains aspect ratio)

• SizeConstraint.Width(100) – resizes the image to the specified width (maintains aspect ratio)

• SizeConstraint.MaxWidthOrHeight(100) – resizes the image so that its width and height do not exceed the specified value (maintains aspect ratio)

• SizeConstraint.Size(100, 120) – resizes the image to the specified width and height, and does not maintain aspect ratio

  Notes:

  • The resized images are never larger than the original size.
  • It is not possible to resize image files via the SizeConstraint parameter when using direct URLs. This is caused by the fact that files accessed from direct URLs are handled directly by IIS.

The FileUrl method allows you to force a file download:

@{
    // Generates a URL for the media file that forces download
    Url.Kentico().FileUrl(mediaFile.PermanentUrl, new FileUrlOptions() { AttachmentContentDisposition = true });
}

Media libraries in an external storage

To store media library files in an external storage (cloud-based file system), you need to:

1. Configure your MVC application to use the given external storage provider for the media library folder. The instructions for configuring MVC applications are the same as for Kentico projects.

   • For Azure Blob storage, see Configuring Azure storage.
   • For Azure CDN, see Configuring Azure CDN.
   • For Amazon S3, see Configuring Amazon S3.

2. Always generate URLs for media files by calling the GetPermanentUrl method of the MediaLibraryHelper class.