@prp-apps-solutions/ui5-message-handler v0.3.1

ui5-message-handler

This packages serves as a lightweight and simple message handling utility using JSONModels and the MessageBox. The main features are custom message handling as well as error handling.

Installation

• NPM: npm install @prp-apps-solutions/ui5-message-handler
• PNPM: pnpm add @prp-apps-solutions/ui5-message-handler

Description & Usage

The error handler and the message handler can be used in your application in parallel. Both handle the messages/errors in a similar way by

• displaying them in a MessageBox
• adding them to a global error model/ one of your message models
• enabling further control handling by providing optional methods for method chaining

Error Handler

The error handler is implemented as a singleton to enforce one error handler for all errors occurring in your application. All errors are added to an error model by default. The error model's name is errorModel. If you want to give the model a different name, provide the modelName property of the error handler instance on initial instantiation.

:bulb: The following usage descriptions contain examples only which may differ from your actual usage.

(Optional) Error Handler - Place Button, MessageStrip and add MessagePopover

You can optionally add a button, a message strip and a message popover to directly display your error messages:

• The button opens the message popover on press while showing the amount of errors as button text.
• The message strip displays the latest error message.
• The message popover displays the details of the errors added to the error model.

Example Usage

Place the controls within a toolbar in the init method of your corresponding controller:

// Main.controller.ts
class Main extends Controller {
    public onInit(): void {
		ErrorMessageControlHelper.getInstance().placeErrorMessageStrip(
			this.getView().byId("MyToolbarId")
		);

        // ...
    }

    // ...
}

The final result may look like this (if an error occurred):

Error Handler – Usage

It is highly recommended to initialize the error handler in your component. Therefore, set a global error handler which can be accessed from all your controllers across your application. Further – if you use a base controller from which all your other controllers inherit –, a convenience method to get this error handler in your base class is also recommended.

• First instantiation in your Component.ts:

export default class Component extends UIComponent {

    // if not passing the second parameter, the model's name will be "errorModel"
    private _errorHandler: ErrorHandler = ErrorHandler.getInstance(this, "myErrorModel");

	public init(): void {
		// call the base component's init function
		super.init();

		// create the error model with the default name
        this.setModel(models.createErrorModel(), this._errorHandler.getModelName());

		// create the views based on the url/hash
		this.getRouter().initialize();
	}

    // ...
}

• (Optional) Convenience method in your BaseController:

export default class BaseController extends Controller {
    // ...
    protected getErrorHandler(): ErrorHandler {
		const errorHandler = this.getOwnerComponent().getErrorHandler();
		return errorHandler;
	}

    // ...
}

• Usage in one of your controller – Odata request failed:

// handle error only
this.getODataModel().create("/<anyPath>", payload, {
    success: (response: any) => {
        // do sth.
    },
    error: (error: OdataError) => {
        // get the error handler and add message to the error model
        this.getErrorHandler().handleError(error);
    },
});

// show custom error message
this.getODataModel().create("/<anyPath>", payload, {
    success: (response: any) => {
        // do sth.
    },
    error: (error: OdataError) => {
        // get the error handler, add message to the error model, and display the custom message
        this.getErrorHandler().showCustomError("My custom error message.", true, {
            title: "Watch out for my error message",
        });
    },
});

// optional method chaining example
this.getODataModel().create("/<anyPath>", payload, {
    success: (response: any) => {
        // do sth.
    },
    error: (error: OdataError) => {
        // any control that's busy state should be set to false
        const control = this.getView();
        
        // any dialog
        const dialog = this.getView().byId("myDialogId")

        // get the error handler and add message to the error model
        // 1. set a controls busy state to false
        this.getErrorHandler().handleError(error).setBusyFalse(control);

        // 2. set busy state of dialog to false and close it.
        //    Attention: closeDialog() is only available, if the control passed to setBusyFalse is a dialog
        this.getErrorHandler().handleError(error).setBusyFalse(dialog).closeDialog();

        // 3. close any dialog
        this.getErrorHandler().handleError(error).closeDialog(dialog);
    },
});

Message Handler

The message handler can be used to display a message box of the following types displaying the corresponding icons and buttons:

• alert
• information
• confirm
• success
• warning

It is also possible to add your messages to a JSONModel for further processing or only adding it to a model.

Message Handler - Usage

• Create a new instance in your controller or Component

// without message model
// controller
private _messageHandler = new MessageHandler(this.getOwnerComponent());
// component
private _messageHandler = new MessageHandler(this);

// with message model
private _messageHandler = new MessageHandler(this, "myMessageModel");

• Create a model for your handler (if not initially done)

// example in your controller with default name 'messageModel'
this._messageHandler.createMessageModel();

// example in your controller with custom model name
this._messageHandler.createMessageModel("myMessageModel");

• Show custom message

// show message
this._messageHandler.showCustomMessage({
	title: "My Custom Title",
	message: "My beautiful message to be displayed",
	messageType: "information"
});

// show message and add to your model – if model exists
this._messageHandler.showCustomMessage({
	title: "My Custom Title",
	message: "My beautiful message to be displayed",
	messageType: "information"
}).addToModel();

• Add message to model only

this._messageHandler
    .setMessage("information", "My beautiful message to add to my model")
    .addToModel();