Overriding a User Interface

Learn how to override an interface in Oracle Communications Unified Assurance.

An override lets you take existing Unified Assurance functionalities and customize them with specific features to meet your business needs. Use overrides instead of custom interfaces when the customizations are small and you want to preserve the original functionality.

For example, you can use overrides to:

Add an extra field to an existing form or column to an existing grid.
Provide a custom splash screen message or add buttons on the login screen.
Add additional columns or special API processing in DDO or CRUD interfaces.

You implement overrides using ExtJS. 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. You must monitor Unified Assurance packages for ExtJS MVC (controllers, model, grid, form, and so on) code changes and re-implement them 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, follow the usual development best practices, such as requirements gathering and testing. You can use the following process:

Designing the override:
1. Determine the interface or interface pieces that you need to override.
  - For the Event List, override event/src/events/crud/view/EventsGrid.js and event/src/events/crud/controller/EventsGridController.js.
  - For API modifications, override <PACKAGE>/src/api/<API>.php and <PACKAGE>/src/<INTERFACE>/crud/model/<MODEL>.js.
  - For action or behavior modifications, override <PACKAGE>/src/<INTERFACE>/crud/controller/<CONTROLLER>.js.
  - For visual modifications of forms, override <PACKAGE>/view/<INTERFACE>/<FORM>.js.
  - For visual modification of grids, override <PACKAGE>/view/<INTERFACE>/<GRID>.js.
  where:
  - <PACKAGE> is the name of the Unified Assurance package.
  - <API>, <MODEL>, <CONTROLLER>, <INTERFACE>, and <GRID> are UI names and classes. Some are plural while others are singular.
2. Determine what you want the interface or interface pieces to do instead.
3. Create a testing scenario.
Developing the override:
1. Create a new folder called overrides in www/packages/.
2. Create subfolders for each override in www/ui/overrides.
3. Create the 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 the ExtJS namespace.
5. Modify files according to your 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.

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 UIExtraPaths and entries for each ExtJS file to the UIExtraRequires tables in the database. The UIExtraPaths contains the folder path relative to $A1BASEDIR, and it requires only one entry per package 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.

Use the following insert statements to add the entries:

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

where:

<PACKAGE> is the new UI package without the type suffix (for example, Custom).
<SUBFOLDER> is the optional subfolder if you are separating projects within the package.
<OVERRIDE CLASS PREFIX> is the ExtJS class prefix that is made up of the package name in upper camel case and any subfolders before the MVC folders (for example, for the path Custom/customTable/crud/view/CustomTableView.js, the override class prefix is Custom.customTable).
<OVERRIDE FULL CLASS> is the full ExtJS class name based on the directory path (for example, for the path Custom/customTable/crud/view/CustomTableView.js, the override full class is Custom.customTable.crud.view.CustomTableView).

Modifying Files

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

The API (.php) can reuse existing API functionality by subclassing.
The ExtJS (.js) requires an override configuration parameter with the full class name that it overrides. This can be found in the original file's Ext.define(). An example override value is Event.events.crud.view.EventsGrid.

Removing or Uninstalling a UI

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

Otherwise, to remove or uninstall a UI:

Remove the entry in UIExtraPaths and all entries in the UIExtraRequires tables:
```
DELETE FROM UIExtraPaths WHERE Namespace = '<OVERRIDE CLASS PREFIX>' AND Path = 'ui/<PACKAGE>';
DELETE FROM UIExtraRequires WHERE Class = '<OVERRIDE FULL CLASS>';
```
where:
- <PACKAGE> is the UI package without the type suffix (for example, customPackage).
- <OVERRIDE CLASS PREFIX> is the ExtJS class prefix that is the package name in upper camel case (for example, for the path Custom/customTable/crud/view/CustomTableView.js, the override class prefix is Custom.customTable).
- <OVERRIDE FULL CLASS> is the full ExtJS class name based on the directory path (for example, for the path Custom/customTable/crud/view/CustomTableView.js, the override full class is Custom.customTable.crud.view.CustomTableView).
Remove the $A1BASEDIR/www/packages/overrides directory.
Reload the UI.

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

To perform the override:

Identify the class and method that you need to override. For the Events grid, the class is Event.events.crud.controller.EventsGridController and the method is onContextMenu.
As the assure1 user, under the document root (for example, /opt/assure1/www), create the directory along the class path:
```
mkdir -p overrides/Event/events/crud/controller
```

Create a class file called EventsGridController.js in the new override directory:

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

Paste the following into the new file:

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');
}
                                        }
                                    });

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

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

Reload the browser.

The overridden class will be loaded.

To check if the override is working:

Identify the view component associated with the override method. For the Events grid, the view component is eventgrid.
Launch the developer console.

Enter the following code:

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

Enter the following code:
```
grid.getController().onContextMenu
```
The console prints the signature of the method.
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

Overrides are only available for -ui type packages.
Define overrides in one folder named www/ui/customOverrides. You can further separate projects with subfolders for each project if desired.
For projects that will be packaged and distributed to customer systems as part of services work, Oracle recommends that the location and package be www/ui/customExampleOverrides as above if at all possible. If not, the package should at least be prefixed with custom and should contain the service provider's name. See Creating Custom Packages for more information about package prefixes and naming.
Define the UIExtraPaths and UIExtraRequires entries in their own separate -schemaDB package when possible for maintainability. Regardless of whether it is in the same package or not, the SQL is differentially updated. See Creating Custom Packages for the requirements of -schemaDB type packages.

Troubleshooting

When debugging the override javascript, you can use console.log() to print logs containing information such as variables and logic to the browser console.

Additional Resources

Title and Copyright Information

Developer’s Guide

G18222-01