Implementing content in Optimizely (version 13)

This article is aimed at those building the website in Optimizely 13 – you set up content types and templates, and configure how the Mediaflow integration behaves. It assumes that the add-on has already been installed and registered according to Installing the Optimizely integration (version 13).

From version 1.2, there are dedicated property types for images, video and SVG, in addition to the combined MediaflowObject property used on many websites.

Mediaflow property types

The integration offers several ways to add Mediaflow media to a content type. Choose the type based on what the editor should be able to select:

Add MediaflowObject as a custom property

Add the Mediaflow picker as a custom property on the model using MediaflowObject:

using Mediaflow.Optimizely.Models;

[Display(GroupName = SystemTabNames.Content)]
public virtual MediaflowObject MediaflowPicker { get; set; }

From MediaflowPicker, you can retrieve information about the selected media – whether it is an image, video or SVG – as well as metadata such as width, height, Mediaflow ID, alt text, description and photographer.

Render media based on type

A simple example of how to display media depending on its type:

@if (Model.CurrentPage.MediaflowPicker.Type == "image" || Model.CurrentPage.MediaflowPicker.Type == "vector")
{
  <img src="@Model.CurrentPage.MediaflowPicker.FileUrl" alt="@Model.CurrentPage.MediaflowPicker.AltText" />
}
else
{
  @Html.Raw(Model.CurrentPage.MediaflowPicker.EmbedCode)
}

The Type property can have the values image, video, vector (SVG) or audio. Images and SVG are rendered as <img>; video is embedded via EmbedCode.

Using MediaflowPicker in lists

Optimizely recommends putting complex properties in a block that is then placed in a ContentArea. Mediaflow also recommends this:

[AllowedTypes(new[] { typeof(MediaflowBlock) })]
public virtual ContentArea MFBlockList { get; set; }

public class MediaflowBlock : SiteBlockData
{
    [Display(
        GroupName = SystemTabNames.Content,
        Order = 1)]
    public virtual MediaflowObject Media { get; set; }
}

Mediaflow in TinyMCE and SVG support

If you want support for Mediaflow in the text editor (TinyMCE), add configuration in Startup.cs:

services.Configure<TinyMceConfiguration>(config =>
{
    config.Default()
          .AddEpiserverSupport()
          .AddMediaflowTinyMcePlugin();
});

After this, a Mediaflow button is displayed in the TinyMCE toolbar. The plugin also configures TinyMCE to preserve SVG markup when editors insert vector graphics. The file picker in TinyMCE always displays images, video and SVG – the file type filter does not affect TinyMCE.

Note: Video is always embedded as an iframe in the TinyMCE editor because TinyMCE does not support inline JavaScript.

Metadata on images in body text

From version 1.2.5, images inserted via TinyMCE retrieve their alt text, description and photographer from the media object when the page is rendered. Changes made later (via Go to media or Edit metadata on the image) are then displayed without the image needing to be inserted again. This is handled by the packaged display template DisplayTemplates/XhtmlString.cshtml, which is active when AddMediaflowViews() is called after AddCms().

If the website has its own XhtmlString.cshtml, it is used instead. Retain the functionality by rendering via Mediaflow's extension:

@using Mediaflow.Optimizely.Utility
@model EPiServer.Core.XhtmlString
@{ Html.RenderXhtmlString(Model.WithMediaflowMetadata()); }

The content saved in the database is not changed. Alt text that the editor has changed for an individual use (in TinyMCE's own image dialogue) is retained; the description and photographer always follow the media object.

Configuration options that affect the build

The following settings (in appsettings.json, see Article 1) control how media behaves and should be decided together with the person building the website.

LimitEmbedType

Controls how video is embedded from Mediaflow. Video can be embedded either as a standard iframe or as inline JavaScript. If the parameter is specified, only the selected option is shown to the user; if no parameter is specified, the user can choose. JavaScript is recommended because it has the best compatibility with Mediaflow's accessibility features.

Note that video is always embedded as an iframe in TinyMCE.

SaveLocation

Controls where images are saved in Optimizely's media section (page = the page's own media folder, any string = a global named folder, empty = the global "Mediaflow" folder). Images are always copied to the web server regardless of the choice. This affects the folder structure editors see – coordinate this with the content model where appropriate.

ForceAltText

When true, alt text must be entered before an image can be inserted (it cannot be empty). Good for accessibility; may slow down editors who insert many images.

FileTypeFilter and AllowedMediaTypes

FileTypeFilter is a comma-separated list of file extensions sent to the Mediaflow picker (e.g. jpg,png,gif) and controls what the editor can see in MediaflowObject properties. The filter does not apply to TinyMCE or the dedicated image, video and SVG properties. AllowedMediaTypes limits which Optimizely media types uploads can create, using fully qualified type names, e.g. Mediaflow.Optimizely.Models.Media.MediaflowImageMedia.

Runtime settings in the admin UI

Some of the configuration can be changed at runtime by an administrator (CmsAdmins, WebAdmins or Administrators – also via Opti ID) under CMS → Admin → Mediaflow (/mediaflow/settings). The menu option is only shown to users with administrator permissions. Values saved here are stored in Optimizely's database and override the default values from appsettings.json for that environment. On DXP, each environment has its own database – configure each environment separately.

Mandatory alt text

Enable Mandatory alt text for images to require editors to enter alt text in the picker before images are inserted. Applies to flows that support alt text.

Global file type filter

Global filetype filter applies to MediaflowObject properties (the combined field). Enter comma-separated file extensions, e.g. jpg,jpeg,png,gif,webp. If the field is empty, the add-on's default list is used. Dedicated image, video and SVG properties still apply their own types. TinyMCE is not affected by the filter.

Virtual role mapping

Map Optimizely virtual roles to Mediaflow refresh tokens (server keys). This controls which Mediaflow library/permissions each editor group can see.

Use Add mapping to add rows. Up/Down changes priority – the first matching role wins. Place specific roles above the wildcard *.

Security: Treat server keys as secrets. We recommend always configuring keys in the server configuration or DXP App Settings rather than pasting them into screenshots or shared documents.

Save and reset

Click Save to apply changes. To discard overrides and reload values from appsettings.json, open /mediaflow/settings/reset. This clears the database overrides for these settings.

Permission to use Mediaflow in the CMS

Editors need to be signed in to the CMS and have one of the following:

• A matching row in the virtual role mapping, or
• A configured fallback key (Key) together with membership of CmsEditors, CmsAdmins, WebEditors, WebAdmins, Administrators or Mediaflow.

With Opti ID: use the role names CmsEditors and CmsAdmins in the role mapping. See the installation article for Opti ID setup.

Usage reporting

The integration can report where Mediaflow assets are used (page context, URLs, users) back to Mediaflow for analysis. This happens automatically when editors insert or use media. 

If your organisation has requirements regarding data processing, include Mediaflow usage in your privacy or DAM documentation.