Migrating to v1.32

Version v1.32 introduced powerful new APIs for customizing the CE.SDK web editor. These new APIs render some of the existing configurations obsolete, requiring code migration to leverage the more flexible new options.

This guide will help you navigate these changes and explain what you need to do to update your integration.

Configuring the Dock#

Until version 1.32, the dock was configured by two configuration options (although most users only used one of them and kept the others default):

• config.ui.elements.libraries.insert.entries and
• config.ui.elements.dock

If your configuration adapted one of these two (mostly config.ui.elements.libraries.insert.entries), you are affected by this change. For now, it is only deprecated and we will try to do an internal migration for you, but this still might include a breaking change depending on how you used the configuration options before.

Breaking Change#

config.ui.elements.libraries.insert.entries was called repeatedly with a context of currently selected blocks. Most users and configurations have not used this behavior and just returned the same static list of entries for every call. In this case, your configuration should work as before, but if you have relied on this fact, you have to migrate your configuration to the new API, listen to selection changes, and update the asset library entries accordingly.

Migration to new APIs#

Defining the dock is now done by our new APIs in a consistent way to all other customizable locations of the editor. With the Dock API, you now have much greater control of how and what is displayed in the dock. This does not only include dock buttons to open asset libraries but also arbitrary buttons and other elements. Please take a look at the Dock API or learn about the general concept here.

If you aren't affected by the breaking change mentioned above, the easiest way to migrate is to first copy your current dock order after the editor has been inialized. This can be done by calling the new cesdk.ui.getDockOrder() method. Now you can take this order and set it during the initialization of the editor by using cesdk.ui.setDockOrder(copiedDockOrder). The old configuration (config.ui.elements.libraries.insert.entries and config.ui.elements.dock) can be removed afterwards.

Of course, you could also just remove the old configuration and use the new API to define the dock order from scratch.

Please note, that changes to the asset library entries are now done by the Asset Library Entry API and the dock order is just referring to these. So if you, for instance, want to add an asset source id to be shown in a library, you have to add this asset source id to the asset library entry and not to the dock order.

// Before
// ======
const config: Configuration = {
  ui: {
    elements: {
      libraries: {
        insert: {
          entries: (defaultEntries) => {
            return [
              // Changing some of the default entries
              ...defaultEntries.map((entry) => {
                if (entry.id === 'ly.img.image') {
                  entry.sourceIds.push('my-own-image-source');
                }
                return entry;
              }),
              // Adding a new entry
              {
                id: 'my-own-entry',
                sourceIds: ['my-own-source']
              }
            ];
          }
        }
      }
    }
  }
};

// After
// ======
cesdk.ui.setDockOrder([
  ...cesdk.ui.getDockOrder(),
  // Add a new button referencing your new entry
  {
    id: 'ly.img.assetLibrary.dock',
    label: 'My Own Entry',
    icon: [...],
    entries: ['my-own-entry']
  }
]);

// Adding your custom entry
cesdk.ui.addAssetLibraryEntry({
  id: 'my-own-entry',
  sourceIds: ['my-own-source']
});

// Updating an existing default entry
const imageEntry = cesdk.ui.getAssetLibraryEntry('ly.img.image');
cesdk.ui.updateAssetLibraryEntry('ly.img.image',{
  sourceIds: [...imageEntry.sourceIds, 'my-own-image-source']
})

Configuring the Asset Replacement Panel#

Similar to the definition of the dock, we deprecate the configuration config.ui.elements.libraries.replace.entries of the asset library entries for the replacement panel. This method is deprecated but we will try to migrate your configuration internally until it is removed. We recommend you to migrate to the new API as soon as possible.

The new API is similar with subtle differences. With cesdk.ui.setReplaceAssetLibraryEntries you register a function that is called with the current context (of selected blocks) but only returns ids of entries.

Breaking Change#

With the config.ui.elements.libraries.replace.entries it was possible to take the default entries and modify them. In theory, you could change the entries and have different "default" entries for insert or replace. Now a change to a default entry provided by the editor via the Asset Library Entry API will be reflected in both the insert and replace entries. To solve this you can just copy one entry for replacement, modify it, and return its id instead.

Migration to new APIs#

Take the function from config.ui.elements.libraries.replace.entries and use it in cesdk.ui.setReplaceAssetLibraryEntries by replacing the entries with their ids. If you have made changes to the default entries or added new custom ones you need to add or change them via the Asset Library Entry API on initialization of the editor.