Customizing icons

As a general rule, it is not possible to customize the icons of third-party library plugins, as it is the plugin’s responsibility to set its icon. However, if we want our plugin to support icon customization, we can use the following APIs from the Paella class instance:

• Paella.getCustomPluginIcon(pluginName,iconName): Get the iconName SVG data for pluginName plugin.
• Paella.addCustomPluginIcon(pluginName,iconName,svgData): Set the iconName SVG data for pluginName plugin.
• Paella.removeCustomPluginIcon(pluginName,iconName): Remove the iconName SVG data for pluginName plugin.
• Paella.requestedCustomIcons: Returns the list of requested custom icons.

Paella.getCustomPluginIcon(pluginName,iconName)

This function is designed to be used from the plugin code. It is used to obtain a custom icon for that plugin. Custom icons are identified by the plugin identifier and a name that has to be unique to that icon, within that plugin.

If the icon has not been customized, then this function will return null. The following example is extracted from the code of the es.upv.paella.playPauseButton plugin, which uses two different icons for play and pause:

import defaultPlayIcon from 'paella-core/icons/play.svg';
import defaultPauseIcon from 'paella-core/icons/pause.svg';

export default class PlayButtonPlugin extends ButtonPlugin {
  async load() {
    const playIcon = this.player.getCustomPluginIcon(this.name,"play") ||
                         defaultPlayIcon;
    const pauseIcon = this.player.getCustomPluginIcon(this.name,"pause") ||
                         defaultPauseIcon;
    this.icon = playIcon;
        ...

If the icon has not been customized, the getCustomPluginIcon function will return null, and therefore the icon defined by the plugin will be assigned. Otherwise the custom plugin will be used.

Because support for icon customization depends on each plugin implementing it via the above APIs, each third-party plugin library must detail whether the plugins it exports are supported, and document the corresponding names of each icon. You can check the documentation of the Paella Player official plugin libraries for more information about the icons that can be customized:

Paella.addCustomPluginIcon(pluginName,iconName,svgData)

On the code side of the video player, the programmer can set the custom icons using this function, which receives the plugin identifier, the icon name and the icon text in SVG format as a parameter. Remember that, as stated in the documentation on button type icons, plugin icons can only be set in SVG format, so this function can only receive icons in SVG text format.

The following code is extracted from the debug player example defined in the paella-core source code. In this case, we have used Webpack’s SVG text importer to load the icon from a file, but we could also pass a valid SVG text string embedded in the JavaScript code:

...
import testIcon from './icons/play_icon_fullscreen.svg';
...

paella.loadManifest()
    .then(() => {
      paella.addCustomPluginIcon("es.upv.paella.playPauseButton","play",testIcon);
    )})
    .catch(e => paella.log.error(e));

Paella.removeCustomPluginIcon(pluginName,iconName) (paella-core >= 1.32)

Allows you to delete a custom icon. This function removes the icon from the custom icon registry, but does not change it in the plugin where it is used. For the changes to take effect, the player must be restarted with the paella.reload() or paella.unload() APIs.

paella.removeCustomPluginIcon("es.upv.paella.playPauseButton","play");
paella.reload();

Summary

There are APIs to customize plugin icons, but it must be noted that the plugin must support it. It may be the case that the developer of a plugin does not want the icon he has used to be modified, and in this case the addCustomPluginIcon function will have no effect.

However, it is still possible to customize the icon if we define a new plugin and override the init method.

// Note: this is an example. Check the actual `paella-basic-plugins` repository
// documentation to get more info about the exported plugin classes.
import { VolumePlugin } from 'paella-basic-plugins';

import MyIcon from '../icons/my-volume-icon.svg';

export default class MyVolumePlugin extends VolumePlugin {
    async load() {
        super.load();
        this.icon = MyIcon;
    }
}

For more information, check the document Customization.

Paella.requestedCustomIcons

Returns the custom icons that have been requested from the paella-core instance. Only returns the plugin identifier and the icon name. It can be used to get the complete list of customizable icons. It is important to note that this function will only return the correct list of icons when the player is in PlayerState.LOADED. Plugin icons that are not active (for example, the subtitle plugin in a video that does not have subtitles) will not be included in this list, because we will only be able to see the icon data that has been requested by the plugin.

paella.bindEvent(paella.Events.PLAYER_LOADED, () => {
  console.log(paella.requestedCustomIcons);
});

paella.loadManifest()
    .then(() => {)})
    .catch(e => paella.log.error(e));

Other icons

Some of the icons that do not belong to any plugin can be customised through the icon customisation API, using the name of the library package as the plugin identifier.

• @asicupv/paella-core:
  • playPreview: modifies the play icon in the preview container that appears before loading the player.

...
import CustomPlayIcon from "./MyCustomPlayIcon.ts";
...
player.addCustomPluginIcon("@asicupv/paella-core", "playPreview", CustomPlayIcon);
...