Media renderer

Note

Media renderer was introduced in version 5.15 and modified in versions after that. Be sure to update to the latest version to take full advantage of all examples in this documentation.

In order to render a retrieved media object, you can use the Html property to get the prepared html code that will display the requested media.

var image = client.Load<Image>(6404)
    .Resize(200, 200)
    .Single();
Console.WriteLine(image.Html);

In ImageVault 5.15, the MediaRenderer concept was introduced. This allows custom handling of how a media item should be rendered.

var image = client.Load<Image>(6404)
    .Resize(200, 200)
    .Single();
var html = MediaRenderer.RenderMedia(image);
Console.WriteLine(html);

The media renderer looks at the RendererId property of the media object and looks up a renderer with that id.

RenderContext

Note

New from ImageVault version 5.16

If you would like to modify how the html is being rendered, you can instruct the renderer by modifying a RenderContext object. The render context can be seen as a dictionary that feeds the renderer with the information it needs to produce the html.

You create a context instance by supplying a Media object. It will pull all properties from the media object into the RenderContext, like name, url, width, height.

var image = client.Load<Image>(6404)
    .Resize(200, 200)
    .Single();
var context = new RenderContext(image);
context.Set(ContextKey.Alt, "Flowers on a field");
var html = MediaRenderer.Render(context);
Console.WriteLine(html);

When you have the media context object, you can modify it's properties by the Set method. When done, pass the context object to the MediaRenderer.Render method.

Another example using the video player that will hide player controls, autoplay when page is loaded with muted audio, and assign the css class "my-video-class".

var video = client.Load<Video>(6405)
    .Resize(200, 200)
    .Single();
var context = new RenderContext(video);
context.Set(ContextKey.Controls, false);
context.Set(ContextKey.Autoplay);
context.Set(ContextKey.Muted);
context.Set(ContextKey.Class, "my-video-class");
var html = MediaRenderer.Render(context);
Console.WriteLine(html);

ContextKey

For ease of use, the ContextKey enum contains common used context dictionary keys. Not all renderers support all keys but the documentation lists the most common usage for them.

RendererId

If you specify a RendererId, this will be used instead of the RendererId specified on the media object.

Existing renderers

There exist a couple of renderers all ready that is used to render standard ImageVault media items.

Renderer	Id	Description
ImageRenderer	F8C54BCD-3B8C-4C63-B6C7-302FA9BA8765	Renders an img tag
AnchorRenderer	65B954CC-4D55-463B-B2D4-EEEEDA30EBA8	Renders an a tag
PapirflyPlayMediaRenderer	D958AB20-FEFA-4DD3-A7DE-BDAE90D32E6D	Renders a video player compatible with ImageVault video service (v3)
PapirflyPlayEmbedMediaRenderer	770D5A54-96C9-49A0-9661-0DA9B8E62FA7	Renders an embedded player (iframe) that wraps the video player above
AzureMediaPlayerMediaRenderer	CF2B805A-597A-4D46-87CA-90F3C9B9B50C	Renders a video player compatible with ImageVault video service (v2)
AzureMediaPlayerEmbedMediaRenderer	BF2B805A-597A-4D46-87CA-90F3C9B9B50C	Renders an embedded player (iframe) that wraps the video player above (also works with ImageVault video service v3)
Html5VideoRenderer	17733ABF-0D07-4F78-BBCB-D81EB5AC9F05	Renders a html5 video tag compatible with ImageVault video (v1)
YouTubeRenderer	65456BEE-FF46-4631-A724-21E73E5A6A62	Renders an embedded YouTube player

Disable server html generation

To speed up server requests, html generated on the server can be disabled. This results in an empty Html property on the media object and instead html generation must be performed using MediaRenderer.

var image = client.Load<Image>(6404)
    .Resize(200, 200)
    .DisableHtml(true)
    .Single();
var html = MediaRenderer.RenderMedia(image);
Console.WriteLine(image.Html);
Console.WriteLine(html);

Custom renderers

If you would like to specify a custom renderer, you implement a class that inherits from IMediaRenderer.

Id

Enter a unique id that is used for identifying the renderer. You can use the same id as any other renderer to override the behavior of that renderer.

GetResourceList

If the renderer needs some resource files, like a css or javascript file, this method should return a list of all needed resources.

Render

This method is responsible for rendering the html based on a supplied RenderContext

public class MyMediaRenderer : IMediaRenderer
{
    public const string RendererId = "enter a guid here";
    public string Id { get { return RendererId; } }
    public string Render(RenderContext context)
    {
        var img = new HtmlTagWriter("img", HtmlClosingTag.Self);
        if (!string.IsNullOrWhiteSpace(context.Options.ClassName))
        {
            img.AddAttribute("class", context.Options.ClassName);
        }
        img.AddAttribute("src", context.Get(ContextKey.Url));
        img.AddAttribute("alt", context.Get(ContextKey.Alt));
        img.AddIfExists("width", context.Get(ContextKey.Width));
        img.AddIfExists("height", context.Get(ContextKey.Height));
        img.AddIfExists("title", context.Get(ContextKey.Title));
        return img.ToString();
    }

    /// <inheritdoc />
    public IList<RenderResource> GetResourceList()
    {
        return null;
    }
}

Using a custom renderer

To be able to use a custom renderer, you must first register it using MediaRenderer.RegisterRenderer. When it's registered the MediaRenderer.Render methods will be able to map it.

To direct MediaRenderer to use the custom renderer, set the RendererId property of the RenderContext object

//register renderer
MediaRenderer.RegisterRenderer(new MyMediaRenderer());
var image = client.Load<Image>(6404)
    .Resize(200, 200)
    .Single();

//create a context object around the media item
var context = new RenderContext(image)
{
    //force use of our new renderer
    RendererId = MyMediaRenderer.RendererId
};
//some properties, like width/height/url is collected from the media object

//add custom properties to the context object
context.Set(ContextKey.Alt, "alternative text");

//render the html
var html = MediaRenderer.Render(context);
Console.WriteLine(html);

Embedded media player

You can also embed the player in an iframe by adding the embed segment before the /publishedmedia/ (or /media/) segment. This will return a page solely containing the html generated by the renderer. You can also pass in context parameters using query string parameters to update the RenderContext values.