Deep Dive into Empress' Dialog API: Exploring frappe.msgprint and frappe.throw

Developers
1

Introduction

Empress offers a collection of standard, interactive, and flexible dialogs that are simple to utilize and configure. These dialogs come with an extensive API for Javascript. In this guide, we will delve into the technical depth of two important features of the Dialog API: frappe.msgprint and frappe.throw.

frappe.msgprint

The frappe.msgprint method works only within a request/response cycle and is used to display a message to the user logged in to the Desk who initiated the request. The method is structured in the following way:

frappe.msgprint(msg, title, raise_exception, as_table, as_list, indicator, primary_action)

This method consists of several parameters:

  • msg: This is the message to be displayed to the user.
  • title: This parameter specifies the title of the modal.
  • raise_exception: This parameter handles the exceptions.
  • as_table: If the msg parameter is a list of lists, it will render as an HTML table.
  • as_list: If the msg parameter is a list, it will render as an HTML unordered list.
  • primary_action: This parameter binds a primary server/client side action.

Here’s an example of how to use frappe.msgprint:

frappe.msgprint(
    msg='This file does not exist',
    title='Error',
    raise_exception=FileNotFoundError
)

frappe.msgprint

The primary_action parameter can contain a server_action or client_side action, which must contain dotted paths to the respective methods. The JavaScript function must be a globally available function. You can also pass hide_on_success to close the message after the action is successfully completed.

frappe.msgprint(msg='This file does not exist',
    title='Error',
    raise_exception=FileNotFoundError
    primary_action={
        'label': _('Perform Action'),
        'server_action': 'dotted.path.to.server.method',
        'client_action': 'dotted.path.to.client.method',
        'hide_on_success': True,
        'args': args
    }
)

frappe.msgprint with primary action

frappe.throw

The frappe.throw method raises an exception as well as shows a message in Desk. It is essentially a wrapper around frappe.msgprint. The method is structured as follows:

frappe.throw(msg, exc, title)

The exc parameter can be passed an optional exception, by default, it will raise a ValidationError exception.

Here’s an example of how frappe.throw is implemented:

frappe.throw(
    title='Error',
    msg='This file does not exist',
    exc=FileNotFoundError
)

frappe.throw

Conclusion

Understanding and using the Dialog API, particularly frappe.msgprint and frappe.throw, can greatly enhance the interactivity and user-experience of your applications in Empress. Not only do these features allow for comprehensive error handling, but they also provide a way to interactively engage with the end-user, making your applications more robust and user-friendly.