How it works

The plugin provides a decorator for the existing content selector or a button in the TinyMCE toolbar, enabling users to choose content from the DAM. Once selected, the content (or a shared embedding) is downloaded and imported into the default Optimizely media management system.

Examples

• Example of the decorator on a Video content reference

Open

Before video selected

Open

After video selected

• Example of the toolbar button in TinyMCE

• Example of Fotoware content picker

Key features of the integration

• Easy to add to both new and existing Optimizely solutions.

• The integration can be removed without affecting utilized assets.

• Automatically synchronize media from the DAM with Optimizely's default asset management system, simplifying the process for developers.

• It is possible to configure content display to show only local media, media from the DAM CDN, or both.

• Allow developers to configure custom media models containing metadata synchronized from the DAM.

Known issues

• When using DXP and Cloudflare, you sometimes need to whitelist the "/EPiServer/Fotoware.ContentPlatform.Plugins.Optimizely/api/picturepark" URL in ALL ENVIRONMENTS.
  To do this, please contact Optimizely support.
  
  

• To create any WAF bypass rule, you will need a WAF bypass agreement signed by the customer. Additionally, a custom domain must be connected to the site; the generic *.episerver.net domain will not work.

Installation and usage

Installing the package

To get started with the plugin, you need to install it from the Optimizely NuGet feed.

The Nuget package is called Fotoware.ContentPlatform.Plugins.Optimizely, and is available at: https://nuget.optimizely.com/package/?id=Fotoware.ContentPlatform.Plugins.Optimizely

Dependencies:

• EPiServer.CMS.UI version 12.18.0

• EPiServer.CMS.TinyMce version 4.2.0

Register in Startup.cs

Navigate to the Startup.cs file and add the following code to the ConfigureServices method to register the plugin with the solution's service collection.

Configure appsettings.json

Implementing the model interface

You must implement the IFotowareMedia interface on a content type that inherits from the Optimizely MediaData class in your solution. This enables additional fields that the add-on uses to maintain synchronization with the original media.

Example implementation of IFotowareMedia

The ModifiedDate property tracks when the media was last changed in the DAM. The plugin uses it to determine whether to download the media.

Configure TinyMCE

To add a button for inserting media from the DAM, include contentplatform-insert-media in the TinyMCE configuration.

Example of TinyMCE configuration

The button is added to the default TinyMCE by default, but if you have custom tinys for blocks with other configurations, you can apply the following: .AddFotowareContentPlatformToTinyMCE(serviceCollection)

Apply UIHint and FotowareConfiguration attributes to Optimize properties

Decorating the Optimizely property with the UIHint attribute will replace the Optimizely built-in content selector with an extended version that supports selecting content from both DAM and Optimizely content.

Example of using the image UIHint

The UIHint attribute can be applied to ContentReference and Url property types.

FotowareConfiguration

You can use the FotowareConfiguration attribute to add settings for rendering in the frontend. This should be used together with the UIHint attribute.

• DisableDefaultMediaSelector - To turn off the default Optimizely Media Selector, set the property to true. The default value is false.

• QueryParameters - An additional query string appended to the media URL, i.e., format=webp&quality=75.

• ImageWidth - The default width of the image imported into TinyMCE. This does not apply to video or PDF files.

Disable the plugin in Optimizely Commerce Asset list

To disable the plugin in the Optimizely Commerce Asset list, set the PreventCommerceEditorIntegration setting to true.

Logging

The plugin has a number of logging information that can be used for information and debugging the integration. Update appsettings.json as the following.

Multiple site configuration

You can configure the plugin to run with Optimizely multi-site scenario by specifying the site ID for each site in the Sites collection in appsettings.json.

SiteId - The ID of the site, which you can find in Admin > Manage Websites.

Customization

Managing the structure of downloaded assets in Optimizely

Fotoware Media imported into Optimizely are organized into a year-month folder structure to facilitate browsing and prevent issues with large media lists in the same folder, which Optimizely doesn't handle well. By default, folders are created based on the year and month when the media was imported. However, you can customize this structure. For example, you could base it on metadata within your solution.

2024/
└── 06/
├── image01.jpg
└── video02.mp4

This customization is achieved by implementing the IFolderResolver interface.

If you want to save the image to "For this page", register this in startup.

Customize the TinyMCE HTML template

You can create custom HTML input when inserting media into TinyMCE, such as filling in the alt text or adding CSS classes.

To do so, implement and register an IFotowareTinyMceTemplate where you implement the GetHtml(ContentReference contentReference, InsertTinyMceMedia insertTinyMceMedia) method.

Event handling with Fotoware events

Example of how to register event handlers for the Fotoware events in an InitializationModule

OnContentDownloading - Raised before downloading a media with the possibility to cancel the action.

OnContentDownloaded - Raised after the media has been downloaded.

How to use in the frontend

Using PropertyFor

@Html.PropertyFor(m => Model.CurrentPage.ImageAsContentReference)

Output

<img alt="image01.jpg" src="/globalassets/fotoware/2024/6/image01.jpg" />

Adding a HTML attribute

@Html.PropertyFor(x => Model.CurrentPage.ContentReferenceOptimizely, new { Attributes = new { @class = "fotoware-image" }

Output

<img alt="image01.jpg" class="fotoware-image" src="/globalassets/fotoware/2024/6/image01.jpg">

Adding a query string

@Html.PropertyFor(x => Model.CurrentPage.ContentReferenceOptimizely, new { QueryStrings = new { format = "webp" } })

Output

<img alt="image01.jpg" src="/globalassets/fotoware/2024/6/image01.jpg?format=webp">

Adding query parameters

@Html.PropertyFor(x => Model.CurrentPage.ContentReferenceOptimizely, new { QueryParameters = "format=webp&quality=80" })

Output

<img alt="image01.jpg" src="/globalassets/fotoware/2024/6/image01.jpg?format=webp&quality=80">

Use CDN URL

@Html.PropertyFor(x => Model.CurrentPage.ContentReferenceOptimizely, new { MediaOptions = new { UseCdnUrl = true } })

Output
<img alt="image01.jpg" src="https://optimizely.preview-picturepark.com/v/TBVACNY3/">

Use CDN URL with the specified width

@Html.PropertyFor(x => Model.CurrentPage.ContentReferenceOptimizely, new { MediaOptions = new { Width = 600, UseCdnUrl = true } })

Output

<img alt="image01.jpg" src="https://optimizely.preview-picturepark.com/v/TBVACNY3/fit-in:600x100000">

Change log

 ## 2.0.0.0 

•  Target .net 8 and .net 6

• Save assets to 'for this page'

• Right-click on asset pane folders to save assets direct to a folder

• Bug: Change API internal path

## 1.1.0.0 

•  Fix bugs filesize

## 1.0.0.0 

•  Initial version