Skip to main content

 

Documentation & User Guides | FotoWare

Episerver Addon for FotoWare: Installation, Configuration and Use

This Episerver Addon integrates Fotoware DAM with Episerver CMS and Commerce

The addon is available from the Episerver Nuget Feed (download links below)

Example Image Property and selection dialog from FotoWare

clipboard_ed70c62b16dacf32f318e9976975fa46c.png

Example TinyMce Toolbox button

clipboard_e6317c2270b46b6cc439ed5a486a5e664.png

How it works

When an asset is selected, the asset is imported into the default Episerver asset management repo and used in an image property (of type ContentReference or Url) or the Rich Text editor. There is also an Episerver scheduled job (to be enabled after installation) which ensures that the imported images and metadata are kept up to date in Episerver if they change in FotoWare.

Key features of the integration:

  1. Easy to add to Episerver solutions, both new solutions and existing ones
  2. The integration can be removed without affecting used assets
  3. Used assets from FotoWare are synchronized into Episerver's default asset management, making it easy for developers that know Episerver to get started
  4. Possible to configure if media show allows only local assets, assets from FotoWare or both
  5. Possible for a developer to configure his own media models containing the metadata that should be synchronized with FotoWare
  6. Since downloaded media becomes standard Episerver media items, Episerver will keep track of which media is used where in the solution

Installation

Find it on Nuget.episerver.com : http://nuget.episerver.com/en/OtherPages/Package/?packageId=FotoWare.PlugIns.Episerver

Approximate time to install and configure the addon: less than 1 hour

Dependencies

  • This addon requires at least EPiServer.CMS.UI 11.15.
  • The addon also automatically adds support for Episerver Commerce and should work on version 12 and above
  • Version 2 of EPiServer.CMS.TinyMce is needed for toolbox button in editor

Configuration

1. Web.config Appsettings:

<appSettings>
    <!-- all these data is to be obtained from FotoWare -->
    <add key="FotoWare:ClientId" value="[Enter your FotoWare guid]" />
    <add key="FotoWare:ClientSecret" value="[Enter your client secret string]" />
    <!-- always domain.com/*episerver* + /FotoWare.PlugIns.Episerver/Authentication/callback  where *episerver* is depending your configuration -->
    <add key="FotoWare:RedirectUri"  value="[A URL for your solution that needs to be defined in FotoWare. Can be different for different environments]" />
    <add key="FotoWare:TenantUrl" value="https://my.fotoware.cloud" />
    <add key="FotoWare:ApiToken" value="[Enter your API token string]" />
    <add key="FotoWare:PresetUrl" value="/fotoweb/me/presets/export/5cc307637c958c34d84dd555" />
    <!-- which asset folder to import images to -->
    <add key="FotoWare:RootFolderId" value="[Enter an id to a media folder in Episerver where you want downloaded assets, for instance 218]" />

    <!-- these are optional
    <add key="FotoWare:AllowedTypes" value=".jpg,.jpeg,.jpe,.gif,.bmp,.png" />
    <add key="FotoWare:ArchiveUrlsToSynchronize" value="/fotoware/archives/5000-Archive,/fotoware/archives/5000-Archive-2" />
    <add key="FotoWare:PreferredDownloadWidth" value="1400" />-->

Note: The ClientId, ClientSecret and RedirectUri values in the web.config file are obtained when registering the application in the Operations Center.
The ApiToken property is obtained in the Operations Center under Site settings - Behavior - Authentication. (API Key value)

It is also possible to implement and register an instance of the IFotoWareSettings (or extended IFotoWareCommerceSettings) interface to take full control of all settings, for instance configuring which metadata to synchronize.

Also in web.config

Upon installation, the profile store needs to add "FotoWareData", used for storing user specific FotoWare data. Be sure it is there.

<profile defaultProvider="x">
      <properties>
       <add name="FotoWareData" type="System.String" />

2. Configuring additional settings

You need to implement the IFotoWareMedia interface on a content type that inherits from Episerver's ImageData class in your solution. This will enable some additional fields which is used by the addon to keep the assets in sync with the original in FotoWare.
 

public class ImageFile : ImageData,  IFotoWareMedia
{ 
    [Editable(false)]
    public virtual string FotoWareUrl { get; set; } //Link back to Fotoware

    [Editable(false)]
    public virtual DateTime FotoWareModifiedDate { get; set; } //for sync job to work
}

The FotoWareModifiedDate property is used to keep track on when the asset was last changed in FotoWare. It should be noted that an update to metadata to an asset in FotoWeb only adds 2 seconds to the modified date, and therefore we need to keep track of this date and time.

3. Add to your Tiny MCE configuration toolbar

The button should be plugged into Tiny MCE automatically. If it doesn't show up, you probably already have a custom config. Search for TinyMceInitialization in your solution and add fotoware-insert-media to your toolbar

4. Decorate your Episerver Property with the FotoWare UIHint

//FotoWareUiHint.FotoWareImage only for ContentReference type
[UIHint(FotoWareUiHint.FotoWareImage)]
public virtual ContentReference ImageAsContentReference { get; set; }

//FotoWareUiHint.FotoWareImageUrl only for Episerver.Url type
[UIHint(FotoWareUiHint.FotoWareImageUrl)]
public virtual Url ImageAsUrl { get; set; }

This will replace Episerver's built in Image editor with an extended one that supports selecting images from FotoWare as well as local Episerver images.

To disable being able to select local images in Episerver you can add another ui hint to your property:

[UIHint(FotoWareUiHint.DisableDefaultEpiserverMedia)]  //important put last in order

5. Scheduled jobs

There are 2 jobs:

Fotoware - Synchronize assets
Normally enabled if you want to sync updates from FotoWare to Episerver. This job will only update assets if it's been updated in FotoWare.

Fotoware - Synchronize assets - Force
Same as above but will always download the latest image and metadata. Only to be run manually if needed.

You may turn on/off scheduled jobs or run them manually in in Admin/config tab/module management/Fotoware.EpiserverAddon/overview in Episerver.

6. Synchronizing metadata from FotoWare to Episerver

===========================

The addon supports synchronizing metadata between FotoWare and Episerver through a mapping schema that is defined in your implementation of the IFotoWareSettings interface. Implement your own IFotoWareSettings and define the mapping schema for metadata that you want to get into the Episerver assets. It should be noted that that are a number of default metadata in FotoWare but this can be extended for each client.

The default mapping schema is set up as follows:

MetadataConfiguration = new NameValueCollection
{
    {"5", "Name"},
    {"25", "Keywords"},
    {"80", "Photographers"},
    {"116", "Copyright"},
    {"120", "Description"}
};

The mapping schema has keys that match the metadata name in FotoWare and the value is the property name in Episerver. Notice that the types need to be the same when changing the configuration; for instance Photographers is a list of strings.

The following example shows how to add a custom metadata to the synchronization:

MetadataConfiguration = new NameValueCollection
{
    {"5", "Name"},
    {"25", "Keywords"},
    {"80", "Photographers"},
    {"116", "Copyright"},
    {"120", "Description"},
    {"998", "EpiserverCustomProp"} // set on imagetype
};

 

7. Controlling the structure of downloaded assets in Episerver [Optional]

===========================

Since FotoWare stores assets in a flat list and Episerver uses a hierarchical structure, assets imported to Episerver is put in a folder structure to help browsing through the imported assets as well as avoiding long list of assets in the same folder which Episerver does not handle in a good way. It is possible to control how the folder structure for assets in Episerver is done. By default, folders are created based on the year and month that the asset was imported into Episerver, but you could use other structures, for instance based on metadata in the solution.

This is done by implementing the IFolderResolver interface.

8. Customize Tiny MCE html template [Optional]

You have the possibility to implement your own input html when inserting in Tiny Mce, for example filling the alt-text or adding some css classes.

This is done by implementing and registering an implementation of IFotoWareTinyMceTemplateResolver where you override GetHtml(ContentReference contentReference, string insertingToContentReference=null)

9. Event handling with FotoWare events

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 in the synchronization job when an asset is deleted or revoked in FotoWare.

Example of how to register event handlers for these events in an InitializationModule:

public void Initialize(InitializationEngine context)
{            
   var events = context.Locate.Advanced.GetInstance<FotoWareEvents>();
   events.OnImageDownloaded += FotoWareHttpClientOnImageDownloaded;
   events.OnImageDownloading += EventsOnOnImageDownloading;
   events.OnImageDeleted += FotoWareHttpClient_FotoWareImageDeleted;
}

10. Logging FotoWare.PlugIns.Episerver

The addon has a number of logging information that can be used for information and debugging the integration. Add this to EpiserverLog.config or your log4net config:

<logger name="FotoWare.PlugIns.Episerver" additivity="true">
  <level value="Info" />
</logger>

11. Extras: Code Samples

In the nuget package under tools, you'll find some code samples of IFolderResolver, IFotoWareSettings and IFotoWareTinyMceTemplateResolver implementations as well as additional scheduled jobs for synchronization of entire archives from FotoWare.

  • Was this article helpful?