Knowledge Base EPiServer CMS Connector

Content reference

Content reference Connector overview and description

The need for QBank Media support in EPiServer Introduction to the Connector package Architectural overview The QBank media selector – the Media Picker Setting up the system

Tab 1 - Overview Tab 2 - Basic settings Tab 3 -TinyMCE Tab 4 – Site settings Tab 5 – Property settings Tab 6 - Maintenance

Overall flow and communication within the Connector Attributes - Media Format, Data Filter, UI Settings, Tiny settings QBank media formats and format syntax Additional formats of an image Built in support for responsive web Rendering with views Rendering inside a rich text field (TinyMCE) Rendering by code The QBankMedia class Events – Modify format settings or the media object Extending the default QBankMedia class The internal QBank API The QBankSampleBlock nugget package

Best practices Use the QBank Media wrapper in templates only if needed Prepare for as many formats as possible Implement custom support for responsive sites Use the Media Segment pattern Year/Month/Day Put the QBank media in a subfolder and hide the top folder Use a local Media-class for the QBank Media

Problem solving 1. Check the Question and Answer section 2. Check that the latest version is used

3. Check the settings 4. Check the EPiServer logs 5. Check the logs in the Web Browser 6. Check on other computers and/or web browsers 7. Install the connector in a clean Alloy site 8. Contact QBank support and include information on how to reproduce the problem

Questions and answers Install/uninstall Using the Connector TinyMCE issues The EPiServer Environment

Getting started / Installation

1. Download and install Visual Studio Express for Web 2015 2. Download Visual Studio extensions for EPi:

http://world.episerver.com/download/Items/EPiServer-CMS/visual-studio-cms-extensions/

3. In Visual Express: > New Project / Visual C# / EPiServer / EPiServer Web Site / Alloy (MVC)

4. Download the QBankEPi-connector and place it in a folder 5. Tools > NuGet Package Manager > Package Manager Settings > Package Sources 6. Add the created folder as a new source 7. Manage NuGet Packages for Solution

NB! This option is only available when debugging has been stopped!

8. Select QBank as package source in dropdown list 9. Install the QBank package 10. Debug project (launches browser) 11. http://localhost:53379/Util/login.aspx?ReturnUrl=%2fEpiserver%2fCMS

Login with your local machine username/password

12. Open EPiServer-admin and go to the QBank section 13. Add QBank to TinyMCE editor 14. Populate the QBank Settings

Deploying to Microsoft Azure - TBD 1. Add nuget.episerver.com/feed/packages.svc to the nuget sources

Build > Publish web site

Connector overview and description

The need for QBank Media support in EPiServer When having the need for working with Media in a professional way in the EPiServer site, QBank offers a solution to that need through the EPiServer Media Connector. Using the EPiServer Media Connector all media handled within QBank are made available to the

site Editors both when working with rich text in TinyMCE and when working with media properties on pages or in blocks. The solution selected for the Connector is to allow Editors in EPiServer to select, and if needed, adjust QBank media from the central repository and then deploy the media into the site. The selection of the Media is done in the Media Picker which is a tool very similar to the QBank administration tool so users will be very familiar with the look and feel of the Media Picker. Media selected and deployed will be placed in the Media store of the EPiServer Site. This makes the solution very robust when it comes to production because every media item will be pre-made and resist on the site. The pre-made formats will also minimize the risk of DOS attacks focusing on image generation overloading the site.

Introduction to the Connector package

The QBank for EPiServer CMS 7.5+ package is created to make it possible to use QBank as a media source for an EPiServer based solution. Within the editorial environment of EPiServer, QBank media is selected and published into the EPiServer media store. The package includes both a UI-editor for the ContentReference and a QBank tool in TinyMCE. Both these tools for selecting media will initiate the publishing of QBank media into EPiServer.

The media created in EPiServer is of the type QBankMedia. Objects of this type will, besides of built in EPiServer media properties, also include QBank Property data, multiple prepared media formats and more.

Architectural overview

The QBank module for EPiServer CMS 7.5+ is built with the goal to make a seamless integration between the two products. As an EPiServer developer one can continue to work with known concepts like using a local ContentReference as a media reference and also use attributes on properties to control the features of the UI. Selected images are actually transformed and published into EPiServer so using them is identical to how you use any media in EPiServer. The first conversion will be made when the editor selects the media the first time. Additional formats and QBank properties will be added later through a scheduled job recommended to run every minute.

It can be noted that each time the user selects an image a new EPiServer media will be created in a predefined folder and the ContentReference will point to this media.

Focus has been made to get the module to work well in a MVC-environment (Razor) but it should be possible to also use it with .NET-forms.

The QBank media selector – the Media Picker

The user can use QBank media in either a property of the type ContentReference or in a rich text property based on the XHtmlString. In both cases a media selector, the Media Picker, will be opened and the author can work with media and select media. This selector is actually not a part of the module but instead part of the QBank service. QBank will continue to develop the Media Picker even after the package is installed so the user can get new features in the Picker even without updating the module.

Setting up the system

The module will need some information like username, password and a service URL to work. All settings are made in the Admin mode of EPiServer under QBank. The first time settings are opened, the Basic configuration tab will be opened. To evaluate the module, just select Fill with evaluation data and the Add the QBank tool to the Tiny-Editor. Now it should be possible to add QBank media to any rich text field in the system. To open up for media to be selected for ContentReferences, one or more ContentReferences properties with the correct attributes need to be added. Read more about this later.

Tab 1 - Overview The first tab of the settings is the Overview. In this part there are no settings but it is possible to see how many media objects there exist in the site and if some have not yet been updated.

If the background job is not running as it should, also this information is available.

Tab 2 - Basic settings Under Basic settings it is possible to enter the user name and password of the service user. It is also possible to enter the different URL:s needed for the system to work. Finally it is possible to tell how media should be arranged and, if responsive light is used, what widths the site should correspond to - at what width should different media be presented.

Tab 3 -TinyMCE If the QBank tool for TinyMCE is used there are some settings to fill in for this to work smoothly. First of all one or more formats or format templates should be selected. These formats could be a number of sets as well. When the media is rendered inside TinyMCE, the html used will be based on one of the three templates shown in this part of the settings. How to create the template is described later.

Image styles are being used in the dialog shown after the media is selected. A number of comma separated CSS classes could be placed in this field. The names shown in the dialog could also be based on texts in a language file if they are placed under /language/qbank/editdialog/viewstyles. Note: These class names MUST NOT include underscore ‘_’. It can also be noted that these classes will only have an impact if the corresponding CSS class is implemented in a CSS hence in the Alloy these style will have no effect. It is also possible to limit the number of templates shown in the Picker and also if the cropping should be on or off. Finally it is possible to enter up to three properties that could be fetched initially from QBank but the edited in the Media Picker.

Tab 4 – Site settings The Site settings data is used mainly for customer that uses multiple sites in EPiServer. In this case it is possible to connect each site to a specific Deployment site and/or Root folder in QBank. This makes it easier to have one QBank repository even though there are separate web sites.

Tab 5 – Property settings Property settings are mainly set by the developer by adding attributes to different properties. In this tab it is however possible for the administrator to override the settings made by the developer. It should be noted that the developer always have the last word so if the code listens to a particular event, it is possible to change the format settings even after the administrator have changed them.

Tab 6 - Maintenance If the QBank Connector has been installed for evaluation and no custom QBank model has been created in the project site one needs to remove media created before uninstalling the Connector. To do an uninstall preparation, mark the checkbox and write DODELETE in the text box then click on ‘Remove existing QBank Media’. Warning! The process will remove ALL QBank Media and it will not be possible to recover it unless a backup is restored.

Overall flow and communication within the Connector The connector communicates a lot with the QBank API during the Editorial work inside EPiServer. The basic settings for this is setup in Admin and a typical access point is http://sales.qbank.se/api/. To get access to the API a username and a password is required and that user needs to have access to the Deployment Site selected in Site Settings.

When selection and deploying media the client side code also makes call to three EPiServer Rest Stores - QBankConverter, QBankMediaStore and QBankSettingsStore. When the Media Picker is opened either from the TinyMCE tools or from the QBank Property editor, a call is made to QBankSettingsStore to get the basic settings to provide to the Media Picker such as selectable formats, current Media id and some translation data. The Media Picker is the opened in an iframe within a modal dialog page and when the Editor has selected an image, this section is sent back and the QBankConverter is called. During this call the first image Blob and Media object inside EPiServer is created. During this call the server will call the QBank API to “order” the deployment based on the selected base format. When the media is deployed QBankConverter will return the call. If ít takes to long to convert the media a timeout is shown to the Editor. If the Media Picker was opened from the TinyMCE tool a set of HTML is finally inserted in the Editor DOM based on the template saved in settings. If the Media Picker is opened from e QBank Media Editor (property) a call is made to QBankMediaStore and a address (URL) is returned to the media thumbnail.

Attributes - Media Format, Data Filter, UI Settings, Tiny settings

To add a QBank Media Picker to a property of the type ContentReference or XHtmlString, one only have to add attributes to that property. After that everything is handled by the module. A typical decoration of a property used for storing QBank images could look like the one below. [MediaFormat("@w300.jpg")] [UIHint(QBankModule.Web.UIHint.QBankMedia)] [UISetting(false)] public virtual ContentReference ProductImage { get; set; } In this example the ProductImage will have a Media Picker as an editor in Edit mode.

Selecting Edit or clicking on the image will open the Picker.

In this case, when the user selects an image, the image will be scaled to 300 pixels width and three alternative images will be created as well with the width 100, 700, 1200 pixels.

The latter can be address by adding /format[n] to the image source URL. To get the second width (700), the URL just need to be written like this. /globalassets/qbank/2015/01/21/flower.png/format2

QBank media formats and format syntax

Media that is selected by the user can be transformed before published into EPiServer. The transformation can be for example resizing, cropping or changing image type. It is possible to use three different syntaxes when adding a format to an attribute or in Admin mode. For video and document only the first syntax, format templates, applies. The first format syntax is a reference to a format template within QBank. To use a format template just write #templateid (e.g. #19) and that template will be used. The second format syntax is a width format and to use this format, just write the width as an integer. Media transformation will be done to jpg-format and the image will keep its proportions after scaling. The third format is a generic format that is written like this: @w300h200.jpg

Additional formats of an image When an image media is selected it will result in a new media object in EPiServer with the image formats selected in the MediaFormat-attribute. It is however possible to add up to nine (9) additional formats for the media. These additional formats could be used for creating a responsive site or to prepare images for print. The only thing one needs to do to mark that more than one formats should be created is to add a semi colon separated list of formats. [MediaFormat("@w300.jpg:@w100.jpg:@w700.jpg:@w1200.jpg")] [UIHint(QBankModule.Web.UIHint.QBankMedia)] [UISetting(false)] public virtual ContentReference ProductImage { get; set; } Note: If a format must be added afterwards, this can be done by adding the new format to the MediaFormats-property of the EPiServer media object and also set the NeedMediaUpdate to false. This will tell the background that the media need another update.

Built in support for responsive web

It is possible to let the module add support for responsive web. This will mean that at different widths entered in Admin, different alternative media will be chosen by adding /format1 – 9 after the image URL. So if the browser has a window width of 480 an image with the size 460 might be shown whilst if the screen is over 1024 pixel wide, an image with the size 640 is shown. If the site implements responsive support for images with some other method or tool the ResponsiveLight.js should be removed by unchecking this in Admin mode. It is however still possible to use the different formats for getting different sized media, the only thing that is removed is the JavaScript file.

Rendering with views

QBank media is displayed using a view. It is however possible to override the default view by adding a view called QBankMedia.cshtml in the DisplayTemplates (Views\Shared\). Below is an example of how this view could look like. @inherits System.Web.Mvc.WebViewPage<EPiServer.Core.ContentReference> @using QBankModule.Web <img src="@Render.Property(this.Model,"url")"

alt="@Render.Property(this.Model,"alttext")" class="qbankmedia" title="@Render.Property(this.Model,"title")" />

<hr /> @Render.Property(this.Model,"url") @Render.Property(this.Model,"alttext") @Render.Property(this.Model,"medianame") @Render.Property(this.Model,"qbankproperty1") @Render.Property(this.Model,"c_person") <hr />

Rendering inside a rich text field (TinyMCE)

It is possible to add a QBank-tool to the TinyMCE-editor that is shown for the XHtmlString. The formats provided for this tool is set in Admin mode for the whole site. Even in this case it could be alternative formats but it can also be multiple formats sets.

The latter gives a possibility for the user to select one amongst several format sets. As an example the user could choose from “Format 200px”, “Format 400px” and “Format 600px”. This means that when the image has been selected it is also possible to select one of three formats. Finally each format set can include a main format and a number of alternative formats which opens up for showing different image size for different media (e.g. mobile or large screen). When the image and one format set have been selected, some html will be rendered inside the rich text area. This html will be based on a template defined in Admin mode. Actually there are three different templates; one for images, one for video and one for documents. The image template might look something like this. <div class="qbankmediawrapper"> <img src="{url}" alt="{alttext}" class="qbankmedia {mediastyle} {metadataclass}" title="{title}" /> <hr /> <p>{translate:/qbank/exampeldata/akey,"Detta visas för att nyckeln inte gick att hitta."}</p>

<p class="qbankproperty1">{qbankproperty1}</p> <hr />

</div> When the template is rendered all parameters are replace with real values or an empty string. A mandatory parameter is called metadataclass. To be able to re-open a media in TinyMCE, this tag must be placed inside the class tag of the image or object tag. The other available parameters are: ·  {url} – Render the media Url ·  {alttext} – Render the alternative text provided by the editor (only images) ·  {title} - Render the title provided by the editor (only images) ·  {mediastyle} – Render the mediastyle class chosen by the editor (only images) ·  {qbankproperty1} – Render the property 1 text provided by the editor (only images) ·  {qbankproperty2} – Render the property 2 text provided by the editor (only images) ·  {qbankproperty3} – Render the property 3 text provided by the editor (only images)

The template needs to have at least the class ‘qbankmedia’. This class should be added for the image tag, the video object tag or the document link. If the media is wrapped in more tags the outer tag should have the class ‘qbankmediawrapper’. There is also a translation feature that has the syntax below: {translate:/qbank/exampeldata/akey,"Detta visas för att nyckeln inte gick att hitta."} The string /qbank/exampeldata/akey is the key for finding the string in the language file. The second parameter is a backup parameter shown if the string cannot be found. It can be noted that the translation is made once when the template content is inserted. It is not a dynamic translation process. Note: The template need to contain valid HTML. Otherwise TinyMCE will rewrite the tags and in some cases the function will the break. E.g. encapsulating p and div tags inside a span tag will not work.

Rendering by code

Each selected media is saved as a standard media object wherever the site is set to save those. This means that it is standard EPiServer code one needs to use to load the media object. It could look something like the code below: // Get the EPiServer reference to the (EPiServer) media var contentReference = new ContentReference(id); // Get the media from within EPiServer var qbankMedia = contentLoader.Get<QBankModule.Models.QBankMedia>(contentReference); // Get the url based on the EPiServer API var url = urlResolver.GetUrl(contentReference); // Get the media id in QBank var qbankMediaId = qbankMedia.QBankMediaId; // Get the value of the property "c_person" var person = qbankMedia.PropertyDataCollection.FirstOrDefault(p => p.Name.Equals("c_person"));

The QBankMedia class

The QBankMedia class inherits from MediaData. The class has some additional properties mentioned below.

int QBankMediaId  The id of the QBank media object.

int QBankObjectId  The base object id of the media object.

string Cropping  Currently selected cropping format.

string OriginalName  The name of the original QBank object.

Blob BinaryData  The main media Blob (image or document)

Blob Format1 .. 9  Additional media in selected formats.

MediaManager.MediaType MediaType  The type of the original media object: Image, Video or document.

string ExternalSource  An external Url to where the media is placed if not placed inside EPiServer. Videos are placed externally.

List<MediaPropertyData> GetPropertyDataCollection 

Gets a collection of QBank properties that was read when the media object was created. Use SetPropertyDataCollection to set the values. 

List<string> GetMediaFormats   

Media formats for main image and the alternative images. Use SetMediaFormats to set the formats. 

It can be noted that some data is saved as serialized Json-objects can be accessed through properties like GetPropertyDataCollection and GetMediaFormats.

Events – Modify format settings or the media object

It is possible to hook into some events in the module. ·       OnMediaInformationEvent – access base information like formats before the media picker is rendered. 

·       OnMediaPickerSettingEvent – access Media Picker settings like UISettings before it is sent to the Picker. ·       OnQBankMediaCreatingEvent – access Media data such as cropping before it is sent to the Picker. ·       OnQBankMediaSavingEvent – access the Media object after it has been selected in the Picker but before it is being saved. 

One is raised when the MediaInformation is ready, before it is sent to the Media Picker. This object contains data about the media that is being edited. The other event is raised before the Media Picker is rendered. In both cases it is possible to modify the settings data before it is sent further. The MediaPickerSettings-object contains information about what formats to use when the image have been selected. A typical use of these could look like this in an initialization module of EPiServer. QBankModule.Core.EventManager.QBankMediaCreatingEvent += QBankMediaCreatingEvent; QBankModule.Core.EventManager.QBankMediaSavingEvent += QBankMediaSavingEvent; QBankModule.Core.EventManager.MediaPickerSettingEvent += MediaPickerSettingEvent; QBankModule.Core.EventManager.MediaInformationEvent += MediaInformationEvent;

Extending the default QBankMedia class

It is possible to extend the default QBankMedia class. This could be done by creating a custom class that inherits from QBankMedia and implement the interface IQBankMedia. See an example below.

[ContentType(GUID = "74B2683A-D8C5-4704-9626-8DB06F027FA9")] public class MyQBankMedia : QBankMedia, IQBankMedia {

[Display( Name="My QBankMedia Data")] public virtual string MyQBankMediaData { get; set; }

} To make use of the class, hook on to the event listener QBankMediaCreatingEvent and return a media object of the custom class. The code could look similar to the one below.

void QBankMediaCreatingEvent(QBankEventArgs e) {

var contentRepository = ServiceLocator.Current.GetInstance<IContentRepository>();

e.QBankMedia = contentRepository.GetDefault<MyQBankMedia>(e.CurrentMediaFolder); }

The internal QBank API

The API included in the module is mostly used for internal work. Contact QBank for a full API library. If the API is called, avoid doing new authentications and Keep the access_token in the OAuth chain instead. Below is a short summary of features that exist.

TokenResponse GetAccessToken()  Get an OAuth Access Token based on credentials.

Media GetMedia(int mediaId)  Get a specific media from QBank. Note: Don’t call this method for each time a page is rendered.

List<DeploymentFile> ListDeployedFilesForMediaId(int MediaId) 

Gets a list of formats already available for a QBank media object.

List<Site> Sites()  Lists the current sites in QBank. This is not necessarily the same sites that exist inside EPiServer.

List<Template> Templates()  Returns all templates available in QBank for a particular site.

Dictionary<string, string> UserSettings() 

Returns the user settings for the admin user.

  

Additional in MediaManager: 

List<MediaPropertyData> GetQBankMediaProperties(Media media) 

Returns all properties for a QBank media object.

Media can also be accessed through the MediaManager calling MediaToBlob or GetMediaStream. MediaToBlob will return a Blob-object with the media and GetMediaStream will return a stream to the object. Both methods will take a mediaUrl as a parameter. Below are two examples on how they could look like: ·       http://v3.qbank.se/api/v1/media/841/download?template=@[crop:1224,144,1030,621]w190.jpg ·       http://v3.qbank.se/api/v1/media/757/download?template=thumb_medium  As one can see, the template format can be very flexible.

The QBankSampleBlock nugget package

A small sample project is available in where some implementation examples could be seen. It is a good idea to install this package in a test environment and look at the examples.

Best practices

Use the QBank Media wrapper in templates only if needed When setting up the Connector there are basically two ways to use the HTML-template for TinyMCE. The basic pattern where the media tag includes the class ‘qbankmedia’ is the recommended way to implement the template. So, a typical template for an image could be likle the one below. <img src="{url}" alt="{alttext}" class="qbankmedia qbankimage {mediastyle} {metadataclass}" title="{title}" /> In this case the ‘qbankmedia’ class will be used as an identifier so when the Editor clicks on a tag in TinyMCE, a check wif that class exist. If it does, the Media Picker will be opened. When moving the image in TinyMCE, the tag will be intact and everything will work fine. A more complex way to use the template is to also include an external wrapper with the class set to ‘qbankmediawrapper’. In this case it will be possible to also add property data from QBank like photographer or something similar. An example of how the templet could look is shown below. <div class="qbankmediawrapper"> <img src="{url}" alt="{alttext}" class="qbankmedia qbankimage {mediastyle} {metadataclass}" title="{title}" /> </div> Also in this case it will be possible to re-open the Media Picker and also delete the whole outer tag but moving the image around will mostly make the outer tag corrupt and hence, updates to the properties will not work. So, if there is no need for implementing property support in TinyMCE, the more basic template structure with only an img-tag should be used.

Prepare for as many formats as possible When selecting media in the Media Picker this media is deployed in one or more formats depending on the QBank settings and/or the attributes on the QBank Content Reference property. To add formats after media has been selected and deployed sss requires some coding. So it is better to add all formats that will eventually be used when setting up the site from the beginning.

Implement custom support for responsive sites Included in the Connector is support for dynamical choice of image format based on the screen size. If the function Responsive Light is activated in the settings, a small set of Javascript will be loaded on each page. This script will run every 300 ms and it will check if the screen size has changed. If it has, all images on the page is checked to see if they are QBank images. If they are an appropriate format of the image is loaded based on the screen size levels set in Settings. The Responsive Light function will out-of-the-box make it possible to have different image formats for different screen sizes. It has however limitations. As an example it will not take into consideration the screen resolution. The Javascript file is also loaded outside of the site bundle so there is probably reasons why rewriting the feature and include it into the solution is a good choice. When building the custom responsive feature, it is good to know that each media can be prepared for up to 9 formats and each format can be access by adding /format[n] to the image name. An example is shown below. /qbank/2015/09/24/louvre-museum-paris.jpg/format2 So, when implementing a new image property, always prepare for the number of formats that can be used and then let the Javascript (or some server side feature) select the correct format.

Use the Media Segment pattern Year/Month/Day To avoid putting every media copy in the same folder it is recommended to use the Media Segment pattern Year/Month/Day. The setting can be found under admin in the tab Basic configuration. So an image URL would then as an example be /QBank/2015/10/30/image.jpg.

Put the QBank media in a subfolder and hide the top folder A suggestion for hiding the media for Editors could be to add a number of year folder under the QBank folder like 2015, 2016, 2017 and 2018. These folder should then not inherit access rights but have one for letting Everyone Read, WebEditors to do anything but Admin and finally let WebAdmins do anything. When this is done the inherit flag should be turned off also in the QBank folder. Finally nor WebEditors or Everyone should have access to the QBank folder.

The QBank folder would now be hidden for Editors but not to WebAdmins and media will also be visible and accessible for visitors (Everyone).

Use a local Media-class for the QBank Media The connector will store the converted media inside the EPiServer site as a media object. It is recommended to not directly use the QBankMedia-class for creating these media object but instead base them on a media class model within the project. Doing it this way opens up for customisation of the media and it also opens up for removal of the connector without the need of updating the media data already created in the site. To implement this two parts need to be created - a Media model implementing IQBankMedia and an Event Listener listening to QBankMediaCreatingEvent. The media model implementation could be very light and look something like the example below. public class OurQBankMedia : QBankMedia, IQBankMedia { } To make the connector use this model instead of the default model an Event Listener should be created and that code could look something similar to the code below. [InitializableModule] [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class QBankInitialization : IInitializableModule { public void Initialize(InitializationEngine context) { QBankModule.Core.EventManager.QBankMediaCreatingEvent +=

QBankMediaCreatingEvent; } public void Uninitialize(InitializationEngine context) { QBankModule.Core.EventManager.QBankMediaCreatingEvent ‐=

QBankMediaCreatingEvent; } void QBankMediaCreatingEvent(QBankModule.Core.QBankEventArgs e) { var contentRepository = ServiceLocator.Current.GetInstance<IContentRepository>();

// Here the custom media type will be used instead of the default media type e.QBankMedia = contentRepository

.GetDefault<Models.Media.OurQBankMedia>(e.CurrentMediaFolder); } } Implementing the code above will make the connector use the model class from within the project instead of the default class QBankMedia and this makes it possible to store media that has no reference to the QBank-binaries. If the QBank-binaries for some reason needs to be removed from the project the custom model class needs to be adjusted. A probable implementation, where current data is still made available, would look something like the example below. public class OurQBankMedia : MediaData { public virtual string ExternalSource { get; set; } public virtual Blob Format1 { get; set; } public virtual Blob Format2 { get; set; } public virtual Blob Format3 { get; set; } public virtual Blob Format4 { get; set; } public virtual Blob Format5 { get; set; } public virtual Blob Format6 { get; set; } public virtual Blob Format7 { get; set; } public virtual Blob Format8 { get; set; } public virtual Blob Format9 { get; set; } public string FormatsAsJson { get; set; } public virtual bool Imagetemplate { get; set; } public virtual int MediaType { get; } // MediaManager.MediaType ‐> int public virtual bool MediaUpdateProblem { get; set; } public virtual string OriginalName { get; set; } public virtual string OriginalSize { get; set; } public virtual string PropertiesAsJson { get; set; } public virtual int QBankMediaId { get; set; } public virtual int QBankObjectId { get; set; } public virtual string SizeInfo { get; set; } public virtual string SizeInfoExtension { get; } public virtual int UpdateRetryLeft { get; set; } public virtual DateTime UpdateRetryTime { get; set; } public virtual bool Videotemplate { get; set; } } A minimal implementation where QBank-data will be inaccessible, and lost if a media object is re-saved, would look like this.

public class OurQBankMedia : MediaData { }

Problem solving

1. Check the Question and Answer section First of all, read through the Question and Answer section and see if some solutions could be applied to the situation. If not, keep reading this section.

2. Check that the latest version is used A common problem is that an older version of the Connector is used and that this version had some bugs. Please check that the latest version is used. In EPiServer the version number can be found by opening the Plugin Manager under Config in Admin mode.

3. Check the settings Many problems arise because of some settings is missing or invalid. Typically the Deployment site or Assets folder is not chosen correctly in the Settings. In some cases it is unclear if it is a settings problem or some problem in the environment preventing the Connector to work properly. A way to narrow the span of problems is to test with the Evaluation settings. To do this, first save the current settings data, secure that the password is known and then reset the settings to Evaluation mode. If the Connector works with the Evaluation settings but not the custom settings it is typically a configuration problem. In this case, try to look through the settings provided from QBank and if that does not solve the problem. Contact QBank for more support.

4. Check the EPiServer logs A lot of events are logged in the Connector as Info. To identify problems a good practice is to temporarily let the log also log Info level events. Analysing the log can then give valuable information to identify the problem.

5. Check the logs in the Web Browser Some logging is built into the Javascript parts of the module. A good practice is to turn on debug mode (F12) in the browser and look at the Console output. In many cases pure log information or error messages will help understanding what is wrong.

6. Check on other computers and/or web browsers Some problems arise only in some environments. It is because of this a good practice to always try to reproduce problems in different browsers and on different machines. In

some cases problems can be related only to a specific browser or in a specific environment. This will help to narrow down the problem.

7. Install the connector in a clean Alloy site The Connector will communicate with QBank and it can also have some dependencies to the site where it is installed. If possible, it is often a valuable test to start a plain Allu site in the environment and install the Connector there. If the problem also occurs in this test site, the problem is probably connected to the environment. If the problem does not occur in the test site with the custom settings, it could be a problem triggered by something in the current site project.

8. Contact QBank support and include information on how to reproduce the problem If following this Problem Solving guide does not help, it is time to contact QBank for more support. When doing this, it will help a lot if the conclusions, logs and other material is attached to the support ticket. If possible, also provide a description of how to reproduce the problem. Access to some environment where the problem exist is a bonus.

Questions and answers

Install/uninstall Question: As a developer I want to install the package in CMS 7 or 8 in Visual Studio but it does not work. What is wrong? Answer: It might be that it is the wrong package that is being selected. For CMS 7 and 8 the version 3.x of the Connector should be chosen. There is also a nuget-pack for administrators to install under EPiServer AddOn section. Check with QBank that the correct package has been delivered. Question: As an administrator I want to install the AddOn-package inside EPiServer but it does not work. What is wrong? Answer: It might be that it is the wrong package that is being selected. For CMS 7 and 8 the AddOn-nuget of version 3.x will be possible to upload from within EPiServer AddOn function. There is however also a nuget-pack for Visual Studio available and this package will not be possible to use. Check with QBank that the correct package has been delivered. It can also be noted that the AddOn-package for AddOn-install inside EPiServer is no longer supported from EPiServer CMS 9. Question: As a developer I have uninstalled the package but the site will display an error message when showing pages that had QBank media on them. Why is that? Answer: When creating QBank media without having used a custom model class inheriting from the QBank class, EPiServer will have references to media that has no longer any supporting classes. When a page is shown the media can not be loaded and hence an error message will be shown. To solve this the package will need to be reinstalled and a the “Prepare for uninstall”-function should be run from under the Maintenance tab in QBank settings. This will however remove all existing QBank Media so if Media needs to stay in place the module needs to stay as well or a developer needs to write some code to resave all QBank media with a media type that exists on the site.

Using the Connector Question: When choosing the QBank tool in TinyMCE or selecting a QBank property the Media Picker is not shown. Why is that? Answer: In most cases this is because the settings have not been set correctly. Most commonly the choice of Deployment Site or Assets folder under Site Settings has not been entered properly. The Media Picker is fetched from the address http://connector.qbank.se/qbank-connector.js . It might be a good idea to try to access the Media Picker code manually to secure that there isn’t a connection problem that is the problem. Another way to test what is wrong is to fill the settings with Evaluation data and test if the Media Picker now is displayed. However, before this step, secure that all current settings are recorded and that the password to the service is known so that the original settings can be restored after the test. If the Media Picker is shown using Factory settings the most probable cause of the problem is that the current QBank settings are not correct and needs adjustments. Question: After selecting a media in the Media Picker the wait-icon appears but after a minute or so a message says that no media was created. This happens in both TinyMCE and in a plain QBank property. Why is this? Answer: The probable case for this is that the QBank Converter service is having a heavy load currently and can not create media within the timeout time. Try waiting for some time and try again. If the problem persist still after 30 minutes, contact QBank support. Question: New images have been uploaded to QBank but they are not seen in the Picker. Why is that? Answer: The most common cause is because the images is not deployed in QBank or they are not deployed to the site id that has been selected in QBank Settings in EPiServer. Question: After choosing a Media the Property dialog will not be shown. Why is that? Answer:

The Property dialog will only be shown when the Media Picker is called from the TinyMCE tool so if the Media Picker has been opened from a QBank property the Property dialog will not be shown. Question: Data entered in the Property dialog is not shown in the HTML added to TinyMCE. Why is that? Answer: The properties and other data in the Property dialog is possible to add if a special tag is placed in the TinyMCE-template. If the template does not include the properties, they will not be rendered. The template can be seen and modified under the TinyMCE tab in the QBank settings. Question: If a new version of some media is deployed in QBank, will that media automatically be updated in EPiServer? Answer: The media version selected when picking the media will be the one stored in EPiServer. Newly deployed versions will not automatically overwrite the old version. However, a reference to the original media is stored within EPiServer so it is possible to add a feature in the site that updates media if that is requested. Note: Even though the cropping information also is stored in EPiServer, special care needs to be taken to handle images that has been cropped so that the cropping is not applied wrongly on the new version of the image.

TinyMCE issues Question: When moving an QBank-image to another part in the editor the properties are not moved together with the image. Why is this? Answer: The QBank Tool will add a set of HTML based on a template to the TinyMCE text. The image within this area can be moved but it will at the same time be disconnected to the outer template. There are two ways of solving this. Either remove the current image and it´s outer HTML with the DEL-button and then reinsert the image and template using the Media Picker. Or, open up the text in the HTML-mode and do the mode there. Finally, a recommendation is not to use the outer wrapper, e.g. <div> class=‘qbankmediawrapper’> in the template unless more advanced property renderings

should take place in TinyMCE. By not having the outer wrapper moving images is much more predictable. Question: Even though placing the cursor in the beginning of the text, the image will be inserted in the wrong position in the text. Why is that? Answer: It is sometimes hard to make TinyMCE add objects at a selected position because TinyMCE tries to place the marker inside a tag. This has little to do with the Connector but one solution is to open up the HTML-mode and insert a small part of HTML <div>HERE</div> where the insertion point should be.

The EPiServer Environment Question: As a developer I want to install the package in CMS 9. Will this work? Answer: Yes. The Connector version 3.x is built for EPiServer CMS 7.5 + 8 and version 4.x is built for EPiServer CMS 9. Question: When viewing the page with QBank media the image does not show. Why is that? Answer: The most common cause for images to be missing is that the Responsive Light feature is activated and that either the alternative sizes has not yet been deployed or that the size settings are wrong. In some cases the images could also have been removed manually from the assets folder by an editor. First of all, check that the image exist in the QBank assets folder. Then check that the job Update QBank Media is running correctly and wait for a minute to make all the queued conversion finnish. If that does not work, check to see that the number of media created is the same as needed by the Responsive Light setting. If, for example, two break levels of 640 and 1024 has been selected in the Responsive Light settings, there has to be three formats prepared for each image. The number of formats prepared could be seen by opening the image i Edit mode and look at the number of formats under the Format tab. Question: There seems to be a scheduled job for Updating the Qbank media? Is it necessary to have this job running? Answer:

If only the basic format of media should be used it is still recommended but not necessary to have the job running. If more than one media format is to be created the job need to run regularly. It can also be noted that some statistical data in Settings will not be correct if the job does not run. Question: The scheduled job for Updating the Qbank media runs every minute? Can this be changed to run every hour instead? Answer: The default time is set to one (1) minute to minimize problems when publishing pages with media. The job will also crawl through all current media to see if changes has occurred. The job will however only grab some hundred media each time so running the job more seldom can create problems if the site contains a lot of media. So, the job could be set to run more seldom but it is not recommended. Question: Not all images available in QBank exist in the QBank folder in EPiServer. Why is that? Answer: Only media selected in the picker will be saved locally in EPiServer. Actually the media stored in EPiServer is only a kind of cache and should not be used by editors directly. Question: Editors uses the media in the QBank folder in EPiServer. How could i prevent this? Answer: A suggestion is to turn of the access rights for Everyone and WebEditors for the QBank-folder and then pre-create and open up access rights for each subfolder (2015, 2016, 2017, 2018 etc) for Everyone and WebEditors. Question: When looking the the start view on the QBank setting some Media has not been converted correctly. Why is that? Answer: This indicates that something has gone wrong when converting images in behind. If the conversion does not go successful the first time a new retry will be done a little bit later and then another try will be done some hours later. Images not converted can be because of a prior connection problem or because the QBank service is overloaded. First check that the job Update QBank Media is running correctly and wait for a while to make all the queued conversion finnish. A look in the job log could also indicate what has gone wrong. Check that the settings is correct by adding a new file to some block or page. If the media is created the connection works.

If the problem is not solved automatically within 48 hours it is possible to open the media that has the problem in Edit mode and reset it manually. Open the media by writing down the id from the error list. The opan any other QBank media in the QBank assets folder. Now change the last number (the id) in the address bar to the number written down and press enter to open the media in EPiServer. Finally, set the ‘UpdateRetryLeft’ property to zero (0) and change the ‘UpdateRetryTime’ property to a time two minutes from now. Save the image and wait for the scheduled job to try to convert the media again. Question: We need to change the size of some images already deployed. How can we do this? Answer: In the current release of the package this is done by writing a custom update feature. A developer should change the size attribute on the page(s) and then do a recursive loop that looks through all QBank Media Assets. If the Media needs to have a new format, the new format should be added through the GetMediaFormats and SetMediaFormats on the QBank Media object. Then the UpdateRetryLeft, UpdateRetryTime properties should be cleared and the media should be re-saved. Now the Update job will automatically update the media with the new formats. Question: The same image seems to exist in several instances in the QBank Assets folder. Why is this? Answer: Each time an image or some other media is selected and used in the Media Picker, a new instance of this media is deployed and saved into EPiServer. This makes it possible to crop images differently on different places and it also increase performance because the media is pre-prepared and also accessible from within EPiServer. So, every media original can exist several times in the Assets folder of EPiServer. Question: We have some problems the we can’t solve. What should we do? Answer: Read through the Problem Solving section and follow the recommendation there.

Work process and Quality assurance

Development and the use of the Product backlog The work with the EPiServer Connector is based on items in the backlog. New feature request are added and the Product Manager regularly looks at the backlog and decides if a new feature should be implemented or not. In some cases custom features, developed for a specific customer, are also added to the Connector so even if the work is fully or partly financed by a customer, all customers still gain from the new feature. The Connector has basically two parts where the package installed in the EPiServer site is one part and the Media Picker is the other part. When it comes to modifications within the Media Picker these changes can be made without any need to install anything at the site. New features within the EPiServer package will be added as soon as the developers add the latest version och the package.

Quality assurance When a new version is ready to release this version is run through a test program. First of all the developers will test the release in a local environment to check for performance issues, security issues and more technical validations. When a new package is created the test program is activated. The test program consists of the following areas:

● Installation test with both Visual Studio nugets and AddOn nugets ● Admin test with language test ● TinyMCE test with multiple Tiny-area test ● Image property test ● Responsive light test ● Coding test ● Removal test

The tests are run on a clean install of the latest Alloy-package from EPiServer and the test is run on major browsers like Chrome, Firefox, IE, Edge and Safari. Besides this test schema, EPiServer also test any new version of the Package. EPiServer also test the package when new versions of EPiServer is released.

Custom test possible It is also possible for Customers to test a new release before it is finalized. By requesting a pre-release for testing, the customer can get a new version before it is released and the customer can then perform test in their own test environment.

Regular quality meetings The Product Manager and the developer meet regularly and discuss how to improve the Quality work of the product. In many cases this will lead to “non-coding-actions” like addition of documentation or improved communication ways.

Versioning When a bug is fixed the third version number will be changed. When a new feature is added the second version number will be increased and when a major breaking change will occur the first version number will change. It can be noted that to handle the breaking changes in EPiServer CMS 9 the major version number was raised to 4 but version 3 and 4 still have the same features.

Problem- and bug-handling If a customer experiences a problem with the Connector the first thing to do is to follow the recommendations around Problem solving. If the problem arise because of a bug in the Connector the idle way to handle this is to provide a way to reproduce the problem. The bug will then be added to the Support Management System and if it is a critical bug, a bug fix or a work around will be presented with high priority. If the bug is of normal or low priority a new release will be planned. This release could also include new features.

Release notes

Change log from version 3.1

Id Version Description

C1 3.1

A feature to remove all QBank media from the local media store in EPiServer has been added in the Admin function. This feature could be used before uninstalling the module. Warning! All local media will be deleted and links and other references will no longer be able to access the media.

C2 3.1

A dataFilter has been added to the ajax-calls in editor_plugin.js (the Tiny plugin). The filter is activated if a newer version than version 1 of jQuery is used as a default version by EPiServer. The filter will adjust the json result from EPiServer, hence, when the return value starts with {}&&, it will be converted to a valid stringified json-object.

3.1.1 No official release

3.1.2 No official release

C3 3.1.3 More console-logging is added when Media is placed in Tiny (editor_plugin.js).

C4 3.1.4 When choosing documents like PDF in the Picker, the conversion was done based on the template, hence often converted to an image. This took time and often lead to a timeout. Also the format saved was not PDF but an image format like jpg. Now the template are not used when converting document.

Bug fixes since version 3.1

Id Version Description

B1 3.1

When using Responsive Light the width settings was always based on the settings chosen when the media was created and not the current values. Now the current values are used if this is marked in Admin.

B2 3.1

When using Responsive Light the media was reloaded many times per second even though no resizing had been done. Now new media is loaded only if the uses changes the size of the screen.

B3 3.1 If no service URL was set, this was not indicated in the UI when running the module. Now a warning is shown if the Service Url has not been configured.

B4 3.1 If a media was not converted correctly no indication was shown in the UI. Now an warning is shown if the media has not been created.B

B5 3.1 If the chosen Assets folder was removed an error occurred in the Tiny plugin. Now a warning is shown instead.

B6 3.1 If the selected media was deleted in the Media Property the Add button could not be used before refreshing the browser. Not the Add-button works also after the Delete-button has been activated.

B7 3.1 Using JQuery 2 as default version for properties will prevent ajax-calls to EPiServer Store to execute and a blank dialog was shown. Note: The jQuery legacy epiJQuery, version 1.7.2, in DojoDashboardCompatiblity is now used when running the Tiny-support class. This is to prevent problems if the site uses a later version like version 2.1 as default jQuery handler for properties.

3.1.1 No official release

3.1.2 No official release

B8 3.1.3 When adding a block from within a ContentArea, where the block had a Xhtml+Tiny-property and where the QBank Tool was included in Tiny, the TextBox went blank instead of showing Tiny.

B9 3.1.3 When using multiple formats in Tiny, the first format was used for all other format.

B10 3.1.3 When moving an image in TinyMCE it was sometimes no longer possible to edit that image until the page is refreshed.

B11 3.1.3 When selecting a none-QBank-image the QBank tools was not deactivated and hence allowed non-QBank files to open. Opening a non-QBank file resulted in an error message.

B12 3.1.3 When saving a custom property setting it was no longer possible to turn the custom value off unless the application was restarted.

B13 3.1.4 In forms mode, having multiple TinyMCE-editors, hence multiple HTML-areas, the inserted media was added to the last active editor, not the current.

B14 3.1.4 If a media was thrown in the waste basket and if the waste basket was emptied the scheduled would crash until the application was restarted.

B14 3.1.4 If the creation of media took a long time and a user selected the same image twice (before the media was converted), an error occurred in the scheduled job.

B14 3.1.4 When selecting media using a ContentReference-property and UIHint, the selected media was not redisplayed if the user choose to change the media directly.

B14 3.1.4 The ResponsiveLight-feature did not work properly for images placed in Tiny.

B15 3.1.5 As a logged in user, it was possible to access the QBank settings page by direct access, e.g. www.site.com/EPiServer/QBankModule/QBankPlugIn.aspx. Now only users that has Admin Access will be able to access it.