Block UI

Overview

Block UI

The svyBlockUI service in Servoy allows developers to block the user interface (UI) temporarily to indicate that an operation is in progress. The plugins.svyBlockUI API allows you to help prevent user interactions during long-running tasks by displaying an overlay with a customizable message and/or spinner animation.

To be able to use svyBlockUI, the Block UI package must be added from Services section of Servoy Package Manager. It can be accessed by code using plugins.svyBlockUI.

Key features:

• Customizable Appearance: Choose from 11 different spinner styles, set overlay colors, and customize messages.

• Progress Updates: Update the displayed message dynamically during the process.

• User Interaction Prevention: The overlay blocks user input to prevent accidental interactions with the background UI.

• Timeouts: Specify a duration to automatically hide the UI blocker after a set time.

Use Cases

Blocking the UI is especially useful in scenarios where user interaction needs to be paused while waiting for a background process or a long running process to complete. Common use cases include:

• Running Reports:

  • When generating detailed reports, which may take a few seconds or minutes.

  • Use a spinner and a message like "Generating report, please wait..." to keep users informed.

• Batch Updates:

  • During bulk record updates or database operations, to avoid conflicts or errors caused by user input.

  • Example message: "Updating records, please do not close the application."

Properties

svyBlockUI provides several properties to customize its appearance and behavior.

These properties can be set before calling the show method for a fully customized experience.

Available Properties:

• delay: Defines the delay (in milliseconds) before the Block UI is displayed after calling show. This prevents the overlay from appearing for very short operations. Default: 250 milliseconds.

• messageStyleClass: Sets a custom CSS class for styling the message displayed in the overlay.

• overlayColor: Sets the color of the background overlay. Default: #ffffff (white).

• overlayOpacity: Specifies the opacity of the overlay, from 0 (fully transparent) to 1 (fully opaque). Default: 0.5 (50% transparent).

• spinner: Selects the spinner animation style. Available options: "Rotating plane", "Double bounce", "Wave", "Wandering cubes", "Pulse", "Chasing dots", "Three bounce", "Circle", "Cube grid", "Fading circle", "Folding cube".

• spinnerBgColor: Sets the background color for the spinner, allowing further customization of its appearance.

Example:

// Customize Block UI properties
plugins.svyBlockUI.delay = 500; // Set delay before showing the blocker
plugins.svyBlockUI.messageStyleClass = "custom-message-style"; // Apply a custom style to the message
plugins.svyBlockUI.overlayColor = "#333333"; // Set overlay background to dark gray
plugins.svyBlockUI.overlayOpacity = 0.8; // Increase overlay opacity to 80%
plugins.svyBlockUI.spinner = "dots"; // Use the "dots" spinner style
plugins.svyBlockUI.spinnerBgColor = "#ffffff"; // Set spinner background to white

Examples

Processing Multiple Files with Dynamic Updates

This example shows how to use svyBlockUI while processing a list of files, providing updates at each step of the process.

// List of files to process
var files = ["file1.txt", "file2.txt", "file3.txt", "file4.txt", "file5.txt"];

// Show the UI blocker with an initial message
plugins.svyBlockUI.show("Starting file processing...");

// Processing each file
for (var i = 0; i < files.length; i++) {
    // Update the message to reflect the current file being processed
    plugins.svyBlockUI.setMessage("Processing " + files[i] + " (" + (i + 1) + " of " + files.length + ")");
    
    // Perform file processing here!

    application.output("Processed: " + files[i]);
}

// Stop the UI blocker after all files are processed
plugins.svyBlockUI.stop();
application.output("All files processed successfully.");

Explanation:

• files: A list of files representing the items to process in the operation.

• show Method: Displays the UI blocker with the message "Starting file processing...".

• Dynamic Updates:

  • The setMessage method updates the message dynamically to show which file is being processed and its position in the list.

  • Example message during execution: "Processing file2.txt (2 of 5)".

• Perform file processing here!: here goes the code for file operations

• Output Logging: Each processed file name is logged using application.output.

• stop Method: Hides the UI blocker after all files are processed, signaling that the operation is complete.