Handling modal boxes to enhance user experience
In our previous post, we explored creating custom graphical user interfaces using widgets. In this post, we'll learn about enhancing user experience through modal boxes.
What is a modal box, and where is it used?
A modal box is essentially a widget interface that appears over the currently active UI or screen and deactivates all other page content until the modal box is closed. The modal box becomes the active focused screen. It can be used to prompt the user to enter information or to display information to the user on a new UI that pops up from the current UI.
Support for modal boxes
Zoho Sprints offers support for opening and closing a modal box widget, and it also allows data communication between these widgets as part of the extension development process. See the supported methods for handling modal boxes in Zoho Sprints extension development in our documentation.
How do the supported methods work?
The above image lists the methods supported in Zoho Sprints for handling modal boxes and illustrates their behavior. Now, let's have a quick overview of how the modal box is invoked and how data flows from the parent UI to the modal box UI.
1. The sdk.dispatch("zs-modal", {url,options}) method is invoked from the parent UI to open a modal box UI.
2. Once the method is invoked, a widget app ID is returned. The modal box is opened and an instance (WidgetApp) is created using the returned widget app ID.
3. A trigger event is set in the modal box by providing a name for the event using the sdk.trigger method. This sdk.trigger method is used to notify the parent widget that the modal box has opened and is ready to receive data.
4. In the parent UI, the WidgetApp.on method is invoked to listen to the trigger event set in the modal box. This method is invoked using the following parameters: trigger event name (set in the modal box widget) and a callback function.
Note: When the sdk.trigger method (mentioned in step 3) is invoked in the modal box widget, it searches for the widget instance that listens to it (based on the trigger event name), and, if found, it executes the function associated with it the parent UI.
➤ Inside this executed function, the widgetApp.emit method is invoked to emit the required data from the parent UI to the modal box widget.
5. In the modal box widget, the sdk.on method can be invoked to listen to the data emitted from the parent UI.
6. When the modal box needs to be closed, the sdk.dispatch("zs-destroy") method can be invoked to close the opened modal box.
This is a generic flow of how the modal box methods are utilized and handled in a Zoho Sprints extension. To understand these in detail, let's check out a use case involving a modal box.
Use case
In the previous post, we demonstrated widgets with a connection between Zoho Sprints and Zoho Bookings that allowed users to book an appointment with a team member allocated to a work item directly from the Zoho Sprints work item page. The output is attached below for reference.
Now, let's use a modal box to enhance this. We'll provide a modal box to allow the user to reschedule the booked appointment if they want to modify the staff or the time of the appointment they booked.
Steps to update the extension
To achieve the above-mentioned extension functionality, along with the other components (creating extension, configuring plugin-manifest.json and creating connection) discussed in the previous post, few other components are required.
1. Add an additional button called Reschedule Appointment as part of the existing Book an Appointment widget on click of which the new modal box will be opened.
2. Create and open a modal box widget to reschedule the appointment by changing the staff and time if needed.
➤ Reschedule Appointment button code in the Book an Appointment widget - This is the code snippet for the Reschedule Appointment button in the Book an Appointment widget.
//Functionality of reschedule appointment button widget Util.rescheduleappointment = function() { var message = "Do you want to reschedule the appointment you booked now?"; //Construct and pass the URL and data to open up the modal box function SuccessHandler(response) { var url = "/app/reschedule.html"; var data = { "staffid": staffid, "serviceid": serviceid, "selecteddate": selecteddate, "bookingid": bookingid }; var width = "800px"; var height = "500px"; sdk.dispatch("zs-modal", { url, options: { width, height } }).then(widgetId => { const widgetApp = sdk.getWidget(widgetId); //To open a modal box and emit data to it widgetApp.on("model.open", () => { widgetApp.emit("model.view", data); }); }); } function FailureHandler(error) { console.error("Error:", error); } //Confirmation message that appears on click of Reschedule Appointment button sdk.dispatch("zs-confirm-message", {message }) .then(SuccessHandler)//If Yes, SuccessHandler function will be invoked .catch(FailureHandler);//If Cancel, FailureHandler function will be invoked } |
- In the above Book an Appointment widget code, when a user clicks the Reschedule Appointment button, a confirmation message asks if they want to proceed or cancel rescheduling the appointment. This confirmation message is prompted to the user using the zs-confirm-message method.
- If they choose to proceed, then the SuccessHandler method is invoked where the URL and data (staff ID, service ID, selected date, and booking ID) are passed to the modal box for rescheduling the appointment. Once these details are constructed, the zs-modal method is used to invoke and open the modal box.
Using the instance of the modal box widget that was created, when the modal box widget is opened, it is captured using the modal.open() method. The model.emit() method is used to emit and pass the constructed data to the modal box.
➤ Modal box widget to reschedule appointment - The modal box UI allows the user to change the staff and time of the appointment and reschedule the appointment.
Reschedule Appointment - Please find the widget code attached in the post.
- In this code snippet, the data passed from the Book an Appointment widget is received using the sdk.on method.
- The Zoho Bookings API to get staff members is invoked using the request method. Similarly, the fetch availability API is invoked using the request method. For both cases, the connection created for Zoho Bookings is passed as a parameter to request method.
- Next, using the Reschedule Appointment button, based on the staff and the time slot chosen, the appointment is rescheduled by invoking the reschedule appointment API. The booking ID parameter received from the Book an Appointment widget is sent as a parameter to the book appointment API along with the staff ID and the time slot chosen by the user in the modal box widget.
- The zs-destroy method to close the modal box widget is invoked as part of the Reschule Appointment button functionality in order to close the modal box once the appointment has been rescheduled.
Note: You can customize the height and width of the modal box to your requirements. If you need to access the primary widget alongside the modal box widget, you can customize the size of your modal box accordingly.
Now that we have explored both the widgets, let's go ahead and test the extension functionality.
Testing the extension
- You can test the widget using the Run option in the Sigma cloud editor. For detailed guidance on testing the extension, read our post here.
- Once you enter into the test environment, install the extension and authorize the connections.
- Next, enter into the work item and access the Book an Appointment widget. Choose the staff, service, and date, and click Check Availability. The available time slots will be displayed. Choose a time slot and click Book Appointment. An appointment will be successfully booked in Zoho Bookings.
- If you want to reschedule the appointment, click Reschedule Appointment. You will be prompted with a confirmation message if you want to reschedule.
- If you choose to proceed, it will open the modal box where you can change the staff and time slot. Once done, click Reschedule Appointment in the modal box. The appointment will be successfully rescheduled.
In this post we have explored the advantages of using modal boxes to enhance the end-user experience. We hope you found this information useful. Keep following this space for more updates. Stay tuned!
SEE ALSO