Optimizely was known as Episerver Current connector supports EPiServer.CMS.UI (>= 11.15.0 && < 12.0.0) |
The Frontify Integration for Optimizely enables you to embed assets from your Frontify Media Library (and other Frontify asset libraries) directly into Optimizely – resulting in a more fluid content creation process. Learn more about how to set multiple libraries in this specific article.
To get started – please read through the requirements and learn how to configure this integration
Requirements
To make use of the Frontify add-on, you're required to use at least EPiServer.CMS.UI 11. The add-on automatically is supported for Optimizely Commerce, as well. To display the add-on in the toolbox of the editor, Version 2 of EPiServer.CMS.TinyMce is needed.
Further, you need to have a Media Library in place; to embed assets from there to Optimizely via Asset Chooser.
Configuration
1. Appsettings in web.config
<appSettings>
<!-- generaly change "my" below to your instance -->
<add key="Frontify:AssetChooserUrl" value="https://my.frontify.com/external-asset-chooser" />
<add key="Frontify:AssetApiUrl" value="https://my.frontify.com/v1/screen/data/" />
<add key="Frontify:MetadataApiUrl" value="https://my.frontify.com/v1/metadata/get/" />
<add key="Frontify:ProjectApiUrl" value="https://my.frontify.com/v1/project/browse/" />
<!-- ApiToken is in format [projectid=apitoken] if only one is used, [projectid=apitoken&projectid=apitoken] if several used, where first one is default -->
<!-- ApiToken is optained in Frontify/project/settings/integrations dialog -->
<add key="Frontify:ApiToken" value="5209=2PvD14hdPoWFZaFWwWk19Ak1kYjwEdpUbhTFsXXX&5211=6AqLejiw2QTAUFQ1VtUqh3eJhCmhq5g4bLacXXXX" />
<!-- which asset folder to import images to -->
<add key="Frontify:RootFolderId" value=""[Enter an id to a media folder in Episerver where you want downloaded assets, for instance 218]" />
<!-- these are optional -->
<!-- AssetChooserMode default is "tiles" -->
<!--<add key="Frontify:AssetChooserMode" value="tree" />-->
<!-- EnableOnAllImages default is "true" -->
<!--<add key="Frontify:EnableOnAllImages" value="false" />-->
<!-- DisableEpiserverDefaultMediaSelector default is "false" -->
<!--<add key="Frontify:DisableEpiserverDefaultMediaSelector" value="true" />-->
<!-- AllowedTypes default is ".jpg,.jpeg,.jpe,.gif,.bmp,.png" -->
<!--<add key="Frontify:AllowedTypes" value=".jpg,.jpeg,.jpe,.gif,.bmp,.png"/>-->
<!-- PreferredDownloadWidth default is "1400" -->
<!--<add key="Frontify:PreferredDownloadWidth" value="2000"/>-->
It's also possible to implement an instance of the IFrontifySettings (or extended IFrontifyCommerceSettings) interface to further control all settings, such as configuring which metadata to synchronize.
2. Configuring Additional Settings
You need to implement the IFrontifyMedia interface on a content type that inherits from Optimizely's ImageData class. This will enable some additional fields, which again, can be used by the add-on to keep your Media Library assets in sync.
public class ImageFile : ImageData, IFrontifyMedia
{
[Display(GroupName = SystemTabNames.Settings)]
[Editable(false)]
public virtual string FrontifyData { get; set; } //Link back to Frontify
[Display(GroupName = SystemTabNames.Settings)]
[Editable(false)]
public virtual DateTime FrontifyModifiedDate { get; set; } //for sync job to work
[Display(GroupName = SystemTabNames.Settings)]
[Editable(false)]
public virtual string IFrontifyMedia.FrontifyCdnUrl { get; set; } // for thumbnails and use of cdn
}
The FrontifyModifiedDate property is used to keep track of when the asset was last changed in Frontify.
3. Add the Frontify Button to Your Tiny MCE Configuration Toolbar
The Frontify button should automatically appear in the Tiny MCE. If it doesn't, you probably already have a custom configuration in place. In this case, search for TinyMceInitialization in your solution and add frontify-insert-media to your toolbar.
4. Add the Frontify UIHint to your Optimizely Property
By default, the plugin will override all UIHint images. To disable this behavior, change the application settings key Frontify:EnableOnAllImages to false. Then, you can use the Frontify UIHints as follows:
//FrontifyUiHint.FrontifyImage only for ContentReference type
[UIHint(FrontifyUiHint.FrontifyImage)]
public virtual ContentReference ImageAsContentReference { get; set; }
//FrontifyUiHint.FrontifyImageUrl only for Episerver.Url type
[UIHint(FrontifyUiHint.FrontifyImageUrl)]
public virtual Url ImageAsUrl { get; set; }
This will replace Optimizely's built-in image editor with an extended one that supports selecting images from Frontify, as well as, local Optimizely images. To disable the selection of local Optimizely images, you can add another UIHint to your property:
`[UIHint(FrontifyUiHint.DisableDefaultEpiserverMedia)] //important put last in order`
To open a specific project library on a property, you need to use the FrontifyProjectAttribute:
`[FrontifyProject(ProjectId: 5211, ProjectGuid: "6AqLejiw2QTAUFQ1VtUqh3eJhCmhq5g4bLacXXXX", UiMode: FrontifyProjectAttribute.UIMode.Tree)]`
Remember to add all projects used in the solution to the app settings "ApiToken".
5. Scheduled Jobs
There are two scheduled jobs:
Frontify - Synchronize assets: This job is enabled by default, and helps you to sync updates from Frontify with Optimizely. This job will only update assets if it has been updated in Frontify.
Frontify - Synchronize assets - Force: This job will always download the latest set of images and metadata. This job will only run manually and if needed.
You may turn on/off the automatic running of scheduled jobs at Admin>config tab>module managment>Frontify.Episerver.Plugin>overview in Optimizely.
6. Synchronizing Metadata from Frontify with Optimizely
The add-on supports the synchronization of metadata between Frontify and Optimizely. For this, implement your own **IFrontifySettings**, and define the mapping schema for metadata that you want to get into the Optimizely assets. The mapping schema has keys that match the metadata name in Frontify, and values that match the property name in Optimizely.
The following example shows how to add custom metadata to the synchronization:
MetadataConfiguration = new NameValueCollection
{
{"title", "Name"},//this is the only one default
{"tags", "Keywords"},
{"meta_copyright_notice", "Copyright"},
{"EpiserverData", "FrontifyInfoToEpiserver"},//example custom metadata
{"image_url", "CdnUrl" },//example custom metadata
{ "description", "Description"},
};
Note that the types need to be the same when changing the configuration. If you use undocumented fields, the names and structure might change.
7. Controlling the Structure of Downloaded Assets in Optimizely
Because Frontify stores assets in a flat list and Optimizely uses a hierarchical structure, assets imported to Optimizely are put into a folder structure to avoid a confusing arrangement of them. It's possible to modify the folder structure for assets in Optimizely. By default, folders are created based on the month assets were imported to Optimizely, but you can also arrange your folders based on metadata. This is done by implementing the **IFolderResolver** interface.
8. Customize the Tiny MCE HTML template
To implement your input HTML for Tiny MCE, fill the alt-text or adding some CSS classes. To do so, register an implementation of
IFrontifyTinyMceTemplateResolver, where you override the getHTML as follows: ContentReference contentReference, string insertingToContentReference=null.
9. Event Handling with Frontify Events
The available events are:
OnImageDownloading: Raised before downloading an asset with the possibility to cancel the action.
OnImageDownloaded: Raised after the asset has been downloaded.
OnImageDeleted: Raised during the synchronization job, if an asset is deleted or revoked in Frontify.
See the example below to learn how to register event handlers for these events in an initialization module:
public void Initialize(InitializationEngine context)
{
var events = context.Locate.Advanced.GetInstance<FrontifyEvents>();
events.OnImageDownloaded += FrontifyHttpClientOnImageDownloaded;
events.OnImageDownloading += EventsOnOnImageDownloading;
events.OnImageDeleted += FrontifyHttpClient_FrontifyImageDeleted;
}
10. Disabling Frontify in Optimizely Commerce asset list
The Frontify add-on for Optimizely Commerce is enabled by default. To disable this, implement and register IFrontifyCommerceSettings.PreventCommerceEditorIntegration
11. Logging Frontify.Episerver.Plugin
The add-on has many logging information that can be used for debugging the integration. To get them, add the following to EpiserverLog.config or your log4net config:
<logger name="Frontify.Episerver.Plugin" additivity="true">
<level value="Info" />
</logger>
12. Extras: Code Samples
On the Optimizely nuget page under tools, you'll find some code samples of IFolderResolver, IFrontifySettings, IFrontifyCommerceSettings and IFrontifyTinyMceTemplateResolver implementations.
For more information on adding multiple libraries, head to our How to Enable Multiple Frontify Libraries for Optimizely article, where you will find more information. |