Development Guide

Exporting MCUX UI Plugin features

What we call "UI Plugin features" are predefined APIs exposed by a static plugin and consumed by the MediaCentral | UX UI Framework.

Plugin features are located under the avid property of the plugin's exports.

module.exports = {
    'avid': {
        'views': {},
        'view-plugins': {},
        'actions': {}
    },
    'anything-else': {}
};

The views, view-plugins and actions are here the "features". Each feature, in its turn, is an object with string IDs as keys and anything else as values.

The 'views' feature

This feature lets plugin register a view, which is the smallest building block of the MediaCentral|UX layout. Views are synonymous to Panes and in the user interface the term Pane is usually used. Panes are views loaded into the tabbed layout of MCUX. They can be loaded standalone as well in which case they usually don't have a tab header.

Note: This feature describes views to be used in production layouts. To register a view for user settings and system settings layouts, please see the 'settings-views' feature.

The valid exported structure is an object containing view configuration and a view factory. ??Feature ID??, in this case, becomes view type, an internal view identity.

'views': {
    '<view-type>': {
        config: {Object},
        factory: {Function}
    }
}

So that working example would look as the following:

var View = require('avid-mcux-view');
module.exports = {
    'avid': {
        'views': {
            'static-plugin-example.example-view': {
                config: {
                    menuName: "Static Plugin Example",
                    singleton: false,
                    useLegacyStyles: false,
                    icon: "path/to/icon/14x13.png"
                },
                factory: function () {
                    return View.create({
                        createElement: function () {
                            var el = document.createElement('div');
                            return Promise.resolve(el);
                        }
                    });
                }
            }
        }
    }
};

Here are some important notes regarding the above snippet:

  • We define a view with the type static-plugin-example.example-view. It is important to prefix view types with the product's name to avoid collisions with other plugins.
  • View configuration may contain the following optional parameters:
    • menuName - Defines a name for the view to be displayed in the Panes Menu. This is also a default tab title. Fallbacks to the view type.
    • singleton - Defines whether multiple view instances may be open at one moment of time. By default, this is set to "false".
    • useLegacyStyles - Defines whether some of the global MediaCentral|UX styles should or should not apply to your view. By default, this is set to "false".
    • icon - Defines path to tab and menu icon.
  • View factory must return an instance of the view.

The 'settings-views' feature

This feature lets plugin register a view to be used both in system settings and user settings.

Exported structure is exactly the same used in the the 'views' feature - an object containing view configuration and a view factory.

Let's see the differences on the working example:

var SettingsView = require('avid-mcux-settings-view');
module.exports = {
    'avid': {
        'settings-views': {
            'static-plugin-example.example-setting-view': {
                config: {
                    settingsType: 'system-settings',
                    name: "Static Plugin Example"
                },
                factory: function () {
                    return SettingsView.create({
                        createElement: function () {
                            var el = document.createElement('div');
                            return Promise.resolve(el);
                        },
                        save: function () {
                            return Promise.resolve();
                        },
                        revert: function () {
                            return Promise.resolve();
                        }
                    });
                }
            }
        }
    }
};

Firstly, configuration object has changed. Here is the list of available options:

  • settingsType - Defines the layout your view will be available at. Possible values are: "system-settings", "user-settings".
  • name - Defines a name to be displayed in the navigation tree. Fallbacks to the view type.
  • settingsGroupId - Defines an ID of the settings group you want to add your view into. Please see the Grouping settings section.
  • settingsGroupName - Defines a name of the group.

Note: settingsType: "user-settings" is not yet supported.

Secondly, a view factory must return an instance of the settings view. Please see the information regarding the Settings View API in the avid-mcux-settings-view package.

Grouping settings

It is possible to group settings into the collapsible groups inside the settings tree.

Let's see how it is made with the example of two configurations:

'static-plugin-example.setting-view-one': {
    config: {
        settingsGroupId: 'static-plugin-example',
        settingsGroupName: 'Static Plugin Example',
        settingsType: 'system-settings',
        name: "Setting 1"
    },
    factory: function () {}
},
'static-plugin-example.setting-view-two': {
    config: {
        settingsGroupId: 'static-plugin-example',
        settingsType: 'system-settings',
        name: "Setting 2"
    },
    factory: function () {}
}

In the above snippet, two settings views are registered. Besides, the first configuration defines settings group as well. The second one only binds to the existing group by defining the settingsGroupId option.

The 'actions' feature

This feature lets adding functional modules called actions. For example, pane or context menu that exists in view was created from actions that are bound to this menu. So if you are developing some feature that you want to bind to the menu by yourself or by another customer of MCUX platform, you may use actions.

Here is the example action:

"actions": {
    "com.avid.example.example-action-enabled.subitem": {
        // public scope is a namespace inside a view
        isEnabled: function (publicScope) {
            var co = publicScope.getCommonObject && publicScope.getCommonObject();
            console.log("Disabled if is commonObject exist", co);
            return !co;
        },
        // function
        handler: function (publicScope) {
            console.log("Action triggered from menu", publicScope);
        }
    }
};

Action declaration has two methods. First isEnabled - will be triggered when a container with action will start to render. For instance, if action is bound to context menu and isEnabled returns false, this menu item won't be shown. Second, handler - is a function that will be triggered when action is called by a bound container, for example, by clicking on an appropriate context menu item.

Setting an active asset

You are able to set and track an asset which is currently being edited. Please see the avid-mcux-active-asset package for details.