Stuart Greig
Optimizely
Nov 18, 2026
visibility 42
star star star star star
(0 votes)

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

Nov 18, 2026

Comments

error Please login to comment.
Latest blogs
Pick images from Optimizely DAM straight into rich text

Rich text editors in Optimizely CMS (SaaS), and in CMS 13.7.0 on sites that use the Content Manager, have a new image button. It puts images from t...

Stuart Greig | Nov 18, 2026

Setting up the TinyMCE image picker, and DAM images in Graph and the CMS REST API

The new TinyMCE image and video pickers put images and video from the CMS and from Optimizely DAM straight into rich text, in Optimizely CMS (SaaS)...

Stuart Greig | Nov 18, 2026

Lessons From the Optimizely Web Experimentation Compromise

Introduction On 16th November 2026, Scott Helme and the team at Report URI published a detailed investigation into malicious JavaScript being serve...

Mark Stott | Nov 17, 2026

From Review to Release: Publishing My First Optimizely OCP App

Building an OCP app is only half the story. This post follows Publish Child Items from its first submission to a live App Directory release: what...

Chirag Khanna | Nov 16, 2026 |

Brilliant and Ignorant: Building an Optimizely Knowledge Base for AI Agents

Claude is a brilliant developer who has never seen Optimizely. How we gave our agents the framework experience a human needs half a year to earn:...

Allan Thraen | Nov 16, 2026 |