Add your own image source to the TinyMCE image picker
In CMS 13.7.0, the TinyMCE image picker lets editors browse images from the CMS and from Optimizely DAM. Images from your own library can also be included. This post shows you how to add them in two ways:
1. A Graph content source. Put your images in Optimizely Graph and register them as a content source, and they then show up in the picker's Browse dialog with no other code. 2. Your own picker, on top of the content source. A command provider adds an entry to the picker's menu that opens your picker, as Browse DAM does for Optimizely DAM.
To show both, I built MyDAM, a mock image library holding a few images. It's only here to prove the point: in a real project the images come from another external system, such as your DAM provider.
The image picker comes with the Content Manager, which needs Optimizely Graph, so your site needs both. The developer post covers setting them up.
A Graph content source
Add your images to Optimizely Graph as an external source, and add a content source in the CMS that points at them.
Put the images in Optimizely Graph
Graph's external data APIs take a content type first, then the items. The content type needs Graph's _ImageItem contract, so the CMS can use its items as images. MyDAM's type adds one property, altText. The image picker uses a property with exactly that name as the alt text, and falls back to the item's name if there isn't one:
{
"label": "MyDAM",
"languages": ["en"],
"preset": "next",
"useTypedFieldNames": true,
"contentTypes": {
"MyDamImage": {
"contentType": ["_ImageItem"],
"properties": {
"altText": { "type": "String", "searchable": true }
}
}
},
"propertyTypes": {}
}
Each item fills in the contract's metadata: _itemMetadata (key, name and type), _assetMetadata (the image's absolute URL, its MIME type and size) and _imageMetadata (width and height). Graph's global contract types list every field. Because the type turns on useTypedFieldNames, property names in the data carry their type (altText$$String), and searchable fields end in ___searchable.
Here's one item from MyDAM's NDJSON file with its action line. In the file, each object is on one line.
{"index": {"_id": "7ea7669d8b355cf899bdce63329c3917", "language_routing": "en"}}
{
"altText$$String___searchable": "Mark, holding a mug, with a parrot on his shoulder",
"_itemMetadata": {
"key": "7ea7669d8b355cf899bdce63329c3917",
"displayName___searchable": "Mark",
"lastModified": "2026-11-17T09:00:00Z",
"type": "MyDamImage"
},
"_assetMetadata": {
"fileSize": 4626421,
"mimeType": "image/gif",
"url": "http://localhost:8000/mydam/mark.gif"
},
"_imageMetadata": { "width": 4096, "height": 4096 },
"_rbac": "r:Everyone:Read",
"_metadata": {
"status": "Published",
"types": ["MyDamImage", "_ImageItem", "_AssetItem", "_Item"]
}
}
Push the type, then the items, using your Graph app key and secret:
curl -X PUT "https://cg.optimizely.com/api/content/v3/types?id=mdam" \
-u "<app key>:<secret>" \
-H "Content-Type: application/json" \
--data-binary @types.json
curl -X POST "https://cg.optimizely.com/api/content/v2/data?id=mdam" \
-u "<app key>:<secret>" \
-H "Content-Type: text/plain" \
--data-binary @data.ndjson
A few things to know:
- The source ID, mdam here, can be at most four characters, using lowercase letters and numbers.
- External sources aren't enabled on Graph accounts by default, and each account can only have a set number of them. Contact Optimizely to request more.
- Sending the full type again deletes the source's data, so push the items again afterwards.
- I pushed MyDAM's items by hand. With a real DAM, a sync from that system, yours or the provider's, keeps Graph up to date.
Graph's docs cover both calls: Sync content types for external data and Sync content data.
Register the content source
In the CMS, a content source points at the Graph source. MyDAM creates one at startup with a hosted service:
using EPiServer.ContentSources;
using EPiServer.DataAbstraction;
namespace OptiAlloy.MyDam;
// Registers the MyDAM images in Optimizely Graph (source "mdam") as a CMS content source.
public class MyDamContentSourceRegistration(IContentSourceModelRepository contentSources) : IHostedService
{
public const string Key = "MyDam";
public async Task StartAsync(CancellationToken cancellationToken)
{
if (await contentSources.GetAsync(Key, cancellationToken) is not null)
{
return;
}
await contentSources.SaveAsync(new ContentSourceModel
{
Key = Key,
DisplayName = "MyDAM",
Type = "graph",
SourceKey = "mdam",
SourceType = "MyDamImage",
KeyFormat = GuidFormat.Digits,
ContentTypeBase = ContentTypeBase.Image,
PropertyMappings = new Dictionary<string, string>
{
["Id"] = "_itemMetadata.key",
["Name"] = "_itemMetadata.displayName",
},
}, cancellationToken);
}
public Task StopAsync(CancellationToken cancellationToken) => Task.CompletedTask;
}
SourceKey and SourceType are the Graph source ID and content type. The CMS creates a hidden content type based on Image for the source. Register the hosted service in Startup:
services.AddHostedService<MyDamContentSourceRegistration>();
Your images in Browse
The image picker's Browse dialog (Content Manager) gets an MDAM section, named after the Graph source ID, and All lists MyDAM's images with the CMS ones.
[Screenshot: custom-source/01-browse-mdam.png: the Browse dialog's MDAM section listing MyDAM's images]
Picking one inserts a permanent link, with the item's altText as the alt text and its width and height. Published pages use the item's own URL, and so does the rich text html in Optimizely Graph. In the rich text json, the image node has the item's URL in url and a CMS reference in internal, here cms://content/MyDam/<key>?loc=en.
Your own picker
Browse is enough for many sources. If your DAM has its own picker, a command provider adds an entry for it to the image picker's menu:
using EPiServer.Cms.Shell.Service;
using EPiServer.DataAbstraction;
namespace OptiAlloy.MyDam;
// Adds "Browse MyDAM" to image pickers, opening MyDAM's own picker in a popup.
public class MyDamCommandProvider : IContentSelectorCommandProvider
{
public Task<IEnumerable<ContentSelectorCommand>> GetCommandsAsync(
ContentSelectorCommandContext context, CancellationToken cancellationToken = default)
{
if (!context.BaseTypes.Contains(ContentTypeBase.Image))
{
return Task.FromResult(Enumerable.Empty<ContentSelectorCommand>());
}
IEnumerable<ContentSelectorCommand> commands =
[
new ContentSelectorCommand
{
CommandId = "mydam",
Label = "Browse MyDAM",
Icon = "image",
ClientModuleUrl = "/mydam/mydam-selector.js",
Configuration = new MyDamPickerConfiguration
{
PickerUrl = "/mydam/picker.html",
ResolveUrl = "/mydam/resolve",
},
},
];
return Task.FromResult(commands);
}
}
public class MyDamPickerConfiguration : IContentSelectorConfiguration
{
public bool MultiSelect => false;
public required string PickerUrl { get; init; }
public required string ResolveUrl { get; init; }
}
The provider only adds the entry when the editor is picking an image. Each entry is a ContentSelectorCommand:
- Label is the menu text, here Browse MyDAM. It's shown exactly as the provider returns it, so translate it in the provider if your editors need other languages.
- Icon is the icon shown next to the label, here the image icon.
- ClientModuleUrl is the address of the browser module that runs when an editor chooses the entry.
- Configuration holds settings for that module. The module gets them with camelCase names, so PickerUrl arrives as pickerUrl.
MyDAM's browser module and picker page are static files in the site's wwwroot/mydam folder. Register the provider in Startup:
using EPiServer.Cms.Shell.Service;
using Microsoft.Extensions.DependencyInjection.Extensions;
services.TryAddEnumerable(
ServiceDescriptor.Singleton<IContentSelectorCommandProvider, MyDamCommandProvider>());
Browse MyDAM now sits in the image picker's menu, between Browse and Upload to CMS. It shows on image properties too.
[Screenshot: custom-source/02-browse-mydam-menu.png: the image picker menu with Browse MyDAM]
The browser module
The module exports execute(configuration, callbacks). MyDAM's opens the picker in a popup and waits for the chosen ID. Then it asks the site for the matching content link and passes it to callbacks.onContentSelected, or calls callbacks.onError if something goes wrong. It only accepts a message from its own popup on the same origin, and stops listening when the popup closes.
// Loaded by the image picker when an editor chooses "Browse MyDAM".
export function execute(configuration, callbacks) {
const picker = window.open(configuration.pickerUrl, "MyDam", "popup,width=960,height=680");
if (!picker) {
callbacks.onError("Allow popups for this site to browse MyDAM.");
return;
}
const stop = () => {
clearInterval(closedCheck);
window.removeEventListener("message", onMessage);
};
const closedCheck = setInterval(() => picker.closed && stop(), 500);
async function onMessage(event) {
if (event.source !== picker || event.origin !== location.origin || !event.data?.myDamId) {
return;
}
stop();
picker.close();
const response = await fetch(`${configuration.resolveUrl}?id=${encodeURIComponent(event.data.myDamId)}`);
if (!response.ok) {
callbacks.onError("The picked image couldn't be found.");
return;
}
const { contentLink } = await response.json();
callbacks.onContentSelected(contentLink);
}
window.addEventListener("message", onMessage);
}
The resolve endpoint
The picker knows MyDAM's IDs, but the CMS wants a content link. There's no public endpoint that turns one into the other, so the site adds one. It gets the item from the content source and returns its content link, and only editors can call it:
using EPiServer.Authorization;
using EPiServer.ContentSources;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
namespace OptiAlloy.MyDam;
// Turns the MyDAM id picked in the popup into a CMS content link.
[Authorize(Policy = CmsPolicyNames.CmsEdit)]
[Route("mydam")]
public class MyDamController(IContentSourceRegistry contentSources) : Controller
{
[HttpGet("resolve")]
public async Task<IActionResult> Resolve(Guid id, CancellationToken cancellationToken)
{
var source = contentSources.Get(MyDamContentSourceRegistration.Key);
var content = source is null ? null : await source.GetAsync(id, cancellationToken);
return content is null ? NotFound() : Ok(new { contentLink = content.ContentLink.ToString() });
}
}
The picker page
With a real DAM, the popup is the provider's own picker. MyDAM's is a simple page that lists the images. When the editor clicks one, it posts the ID back to the CMS window:
card.addEventListener("click", () => window.opener?.postMessage({ myDamId: card.dataset.id }, location.origin));
[Screenshot: custom-source/03-mydam-popup.png: MyDAM's picker page in a popup]
The image goes into the text as a permanent link, the same as when it's picked from Browse.
Read more
- How editors use the image picker
- Setting up the image picker, and DAM images in Graph and the CMS REST API
- Optimizely Graph: Sync content types for external data, Sync content data and global contract types
Comments