SoFinder: SoEditor’s best companion

We recommend SoFinder as SoEditor’s best asset management companion: SoEditor edits HTML content; SoFinder manages and selects assets. Together in your CMS, they let authors choose images, insert file links and use video URLs with the default video tools.

Visit SoFinder · Official editor integration documentation · Try the asset picker example

How they work together

CMS task	Responsibilities
Article and product images	SoFinder manages and selects images; SoEditor inserts them and edits alternative text and layout.
Attachments and downloads	SoFinder returns a file URL; SoEditor inserts a link through its file selection command.
Video assets	Get a video URL from SoFinder and enter it in the video dialog. Video is enabled by default; this example does not add a picker button to that dialog.
Uploads and storage	Your SoFinder deployment owns uploads, access permissions and storage. Direct editor uploads still need a separate upload adapter.

SoFinder is optional and connects through a separate package. The default editor does not load its management interface or server SDK.

Install and create the editor

Configure your own server and resources following the SoFinder documentation, then install the editor adapter:

pnpm add @soeditor/editor@1.6.0 @soeditor/presets@1.6.0 @soeditor/adapter-sofinder@1.6.0 @soeditor/file-manager@1.6.0

Place these functions in your project’s api.ts. Import createClassicEditor as createOptionalEditor from @soeditor/editor/cms/optional, cmsRuntimePreset from @soeditor/presets/cms-runtime, and FileManagerPlugin, UploadPlugin, fileManagerServiceToken from @soeditor/file-manager. Import SoFinderAdapter and the SoFinderPicker type from @soeditor/adapter-sofinder, the ClassicEditor type from @soeditor/editor/cms, and load @soeditor/editor/cms/styles.css.

export async function createAssetEditor(host: HTMLElement) {
    return createOptionalEditor(host, {
        plugins: [...cmsRuntimePreset.plugins, FileManagerPlugin, UploadPlugin],
        toolbar: [
            'undo',
            'redo',
            'bold',
            'italic',
            'image-browse',
            'file-link',
        ],
    });
}

An explicit plugins list replaces the defaults, so retain cmsRuntimePreset.plugins. Register the picker service:

export function registerSoFinder(editor: ClassicEditor, pick: SoFinderPicker) {
    editor.editor.services.register(
        fileManagerServiceToken,
        new SoFinderAdapter({ pick }),
    );
}

Connect the real SoFinder picker

Replace these deployment paths and the Images / Files resource names with your own routes and configured resources. The official documentation site is not your asset backend. ./api refers to the local module containing the two functions above.

// Use the picker module served by your own SoFinder installation.
import { openPicker } from '/sofinder/assets/sofinder-picker.js';
import { createAssetEditor, registerSoFinder } from './api';

const host = document.querySelector('#content');
if (!host) throw new Error('Missing #content textarea');
const editor = await createAssetEditor(host);
registerSoFinder(editor, async ({ kind }) => {
    try {
        const entry = await openPicker({
            baseUrl: '/sofinder/browser',
            kind: kind === 'image' ? 'image' : 'file',
            resource: kind === 'image' ? 'Images' : 'Files',
        });
        return {
            url: entry.url,
            name: entry.name,
            ...(entry.mimeType ? { mimeType: entry.mimeType } : {}),
            ...(entry.assetId ? { assetId: entry.assetId } : {}),
            ...(entry.alt != null ? { alt: entry.alt } : {}),
            ...(entry.width != null ? { width: entry.width } : {}),
            ...(entry.height != null ? { height: entry.height } : {}),
        };
    } catch (error) {
        if (error instanceof DOMException && error.name === 'AbortError') {
            return null;
        }
        throw error;
    }
});

The official openPicker validates window messages. Convert its window-close AbortError to null and propagate other errors. Non-image dimensions may be null; omit them before returning a selection to the adapter. This bridge maps media requests to file selection; the host must still apply the requested file-type constraints.

React, Vue and the live example

The React and Vue CMS components can call the same registerSoFinder in onReady / @ready. Configure the plugins above through the optional entry when creating the instance. The component guides explain their current release status.

Run asset selection and mock upload: this example uses SoFinderAdapter with a fixed image callback, without a live SoFinder backend. Replace pick to connect your own library. Your host owns authentication, resource access and upload configuration.

Unified image and link APIs (Unreleased)

Current source adds createSoFinderBrowserAdapters (@soeditor/adapter-sofinder/browser) and shared file/internal-page providers for Link and Image link properties, without adding three separate asset shortcuts to the default toolbar. See the repository integration reference. These APIs are not published in 1.6.0; the examples below retain its existing injected adapters.