Overriding a User Interface

Learn how to override an interface in Oracle Communications Unified Assurance. An override is the process of taking existing Unified Assurance functionality and customizing it to meet a particular business need. Similar to Creating Custom Interfaces, overrides should be used when customizations to an interface are small and the original functionality should be preserved (for example, adding an extra form field or grid column). Overriding a Unified Assurance user interface allows for specific and custom features that make sense to the business. A few of these might be:

ExtJS overrides change the functionality of existing classes by replacing member functions and properties with matching members from the new class.

Note:

Unified Assurance functionality changes through package updates will NOT be propagated to overrides. It is the Override Maintainer's responsibility to monitor Unified Assurance packages for ExtJS MVC (controllers, model, grid, form, etc.) code changes and re-implement in overrides.

About Overriding a User Interface

Overrides must follow the same model-view-controller (MVC) structure as a custom interface. See Creating Custom Interfaces for more details.

When overriding a UI aspect, you should follow the usual best practices in development, such as requirements gathering and testing. The following is an outline of the process Unified Assurance follows when developing a UI override:

  1. Design

    • What interface or interface pieces do you need to override?

      • If it is the Event List, override

        event/src/events/crud/view/EventsGrid.js and event/src/events/crud/controller/EventsGridController.js

      • If it is the API modification, override

        /src/api/.php and /src//crud/model/.js

      • If it is an action or behavior modification, override

        /src//crud/controller/.js

      • If it is a form visual modification, override

        /view//

        .js

      • If it is a grid visual modification, override

        /view//.js

    • What do you want the interface to do instead?

    • Create a testing scenario.

  2. Development

    1. Create a new folder "overrides" in www/packages/.

    2. Create subfolders for each override in www/ui/overrides.

    3. Create MVC folder structure within and copy over any original interface parts to override. See Creating Custom Interfaces for more details about the MVC convention.

    4. Add new package and class to ExtJS namespace.

    5. Modify files as per design requirements. See Modification of Files for more details.

    6. (Optional) Package the new -ui type package. See Creating Custom Packages for information on how to create a custom installable package.

Tokens:

<PACKAGE> - Unified Assurance package
<API>, <MODEL>, <CONTROLLER>,<INTERFACE>,<GRID> - UI names and classes. Some are plural while others are singular.

Adding New Package and Class to ExtJS Namespace

In order for the Unified Assurance platform to recognize a new package there must be an entry for the package folder in the UIExtraPaths and entries for each ExtJS file to the UIExtraRequires tables in the database. The UIExtraPaths contains the folder path relative to $BaseDir and only one entry per package is required regardless of how many overrides are within it. The UIExtraRequires entries ensure the files are loaded and recognized as an override and every ExtJS file must have an entry.

INSERT INTO UIExtraPaths (Namespace, Path) values ('<OVERRIDE CLASS PREFIX>', 'packages/<PACKAGE>');
INSERT INTO UIExtraRequires (Class) values ('<OVERRIDE FULL CLASS>');

   <PACKAGE> - new 'ui' package without type suffix (e.g.Custom)
   <SUBFOLDER> - **Optional** subfolder if separating projects within the package
  <OVERRIDE CLASS PREFIX> - ExtJS class prefix that is the package name upper camel case and any subfolders before the MVC folders (e.g. Custom/customTable/crud/view/CustomTableView.js -> prefix: Custom.customTable)
   <OVERRIDE FULL CLASS> - Full ExtJS class name based on the directory path (e.g. cCustom/customTable/crud/view/CustomTableView.js-> class: Custom.customTable.crud.view.CustomTableView)

Modification of Files

Overriding is very similar to creating custom interfaces, with two key differences:

Removing/Uninstalling

If it was installed as part of a package management, assisted uninstall is not supported.

Otherwise:

  1. Remove class path and all extra requires: 

    DELETE FROM UIExtraPaths WHERE Namespace = '<OVERRIDE CLASS PREFIX>' AND Path = 'ui/<PACKAGE>';
DELETE FROM UIExtraRequires WHERE Class = '<OVERRIDE FULL CLASS>';
    where:

    • <PACKAGE> - 'ui' package without type suffix (for example, customPackage)

    • <OVERRIDE CLASS PREFIX> - ExtJS class prefix that is the package name upper camel case (for example, Custom/customTable/crud/view/CustomTableView.js -> prefix: Custom.customTable)

    • <OVERRIDE FULL CLASS> - Full ExtJS class name based on the directory path (for example, Custom/customTable/crud/view/CustomTableView.js -> class: Custom.customTable.crud.view.CustomTableView)

  2. Remove $A1BASEDIR/www/packages/overrides directory.

  3. Reload the UI.

Example

In this example, you override the Event context menu function to show the Event Type of the selected menu as the context menu title.

First, identify the class and method that you need to override. For Events grid, the class is Event.events.crud.controller.EventsGridController and the method is onContextMenu. In this example, the ExtJs class override is implemented as follows:

Ext.define('overrides.Event.events.crud.controller.EventsGridController', {
    override:      'Event.events.crud.controller.EventsGridController',
    onContextMenu: function(gridView, rec, node, index, e) {
    var grid = this.getView();

            this.callParent(arguments);

    if (grid.contextMenu) {
       grid.contextMenu.setTitle(rec.get('EventType'));
       grid.contextMenu.setTitleAlign('center');
    }
                                            }
                                        });

To perform the override:

  1. Under the document root (for example, /opt/assure1/www), create the directory along the class path with assure1 user:

    mkdir -p overrides/Event/events/crud/controller

  2. Create the above override class file in the new override directory:

    cp EventsGridController.js /opt/assure1/www/overrides/Event/events/crud/controller

  3. Paste the contents from the example above into the new file.

  4. Insert the classpath into the UIExtraRequires table. As assure1 user, launch a1db and run the following query:

    INSERT INTO UIExtraRequires (Class) VALUES ('overrides.Event.events.crud.controller.EventsGridController');

  5. Reload the browser. The overrided class will be loaded.

In order to check the method is overrided and the override is working, first you need to identify the view component associated with the override method. For events grid, the view component is eventgrid.

To check if the override is working:

  1. Launch the developer console.

  2. Enter the following:

    grid = Ext.ComponentQuery.query('eventgrid')[0];

  3. After that, enter the following:

    grid.getController().onContextMenu

    This will print the signature of the method.

  4. Click on the method signature. You will automatically jump to the Sources tab and be shown the source code of onContextMenu. If the override is working, the source code should be the same as the override method.

Best Practices

Troubleshooting

Additional Resources