Windows, Dialogs and Popups

Overview

In Servoy, windows, dialogs, and pop-ups provide ways to present content, interact with users, or gather input. These elements allow developers to present various types of interfaces, ranging from simple yes/no dialogs to complex non-modal forms, enabling dynamic and flexible user experiences. The API allows developers to create and manipulate windows programmatically, offering various customization options, such as modal or non-modal behavior, size, title, and positioning. Understanding the correct use of these elements ensures a smooth user interface flow and optimal interaction.

Creating and Accessing Windows

Windows in Servoy can be created using the application.createWindow method or accessed with application.getWindow. The window API allows for the customization of window properties, such as the title, size, location, and visual style (CSS class). This allows for great flexibility when creating pop-ups or dialogs.

Creating a Window

To create a new window object in Servoy, you use the application.createWindow method. This method allows you to create different types of windows such as modal dialogs, non-modal dialogs, or standard windows. The new window can display a form, and you can customize its behavior, size, location, and appearance.

Steps to Create a New Window Object:

  1. Create the Window: Use the application.createWindow method to create a new window object. This method returns a window object, which you can further customize.

  2. Set Window Properties: Optionally, set the size, location, title, and other properties of the window.

  3. Show the Form (Optionally): Use the show() method on the window object to display a form inside the window.

Syntax:

var window = application.createWindow(windowName, windowType);
  • windowName: A string that defines a unique name for the window. This is used to reference the window later.

  • windowType: The type of window you want to create, specified as:

    • JSWindow.DIALOG: Creates a non-modal dialog window (the user can interact with other windows while this one is open).

    • JSWindow.MODAL_DIALOG: Creates a modal dialog window (blocks interaction with other windows until this one is closed).

    • JSWindow.WINDOW: Creates a standard window that behaves like a normal application window.

Setting Window Properties

In Servoy, the window object provides various methods and properties to customize the appearance, behavior, and interaction of windows (modal dialogs, non-modal dialogs, and standard windows). You can find here more information about windows.

Here’s an overview of the main APIs for interacting with a window object, including how to set the title, style class, size, position, and other properties.

Sets the title of the window. This is the text that appears on the title bar of the window (unless the window is undecorated). title: A string representing the title of the window. Example:

win.title = 'Custom Popup Window';

Determines whether the window should have a title bar and borders. If set to true, the window will not display a title bar or borders and it can't be moved/resized or closed (i.e., it will be undecorated). true: The window is undecorated (no title bar or borders). false: The window is decorated (default). Example:

window.undecorated = true;  // Hide the title bar and borders

Sets the size of the window in pixels. width: The width of the window in pixels. height: The height of the window in pixels. Example:

window.setSize(400, 300);  // Set the window to 400px wide and 300px tall

Sets the position of the window on the screen, where x is the distance from the left edge of the screen, and y is the distance from the top edge. x: The horizontal position of the window (in pixels). y: The vertical position of the window (in pixels). Example:

window.setLocation(200, 150);  // Position the window 200px from the left and 150px from the top

Sets whether the window can be resized by the user. By default, windows are resizable. true: The window can be resized by the user. false: The window size is fixed and cannot be resized. Example:

window.resizable = false;  // Make the window non-resizable

Sets the transparency level of the window. This controls how transparent the window appears. opacity: A float between 0.0 (completely transparent) and 1.0 (completely opaque). Example:

window.opacity = 0.8;  // Set the window opacity to 80% (slightly transparent)

Sets the CSS class of the window for styling purposes. You can use custom CSS to style the window when using the NG Client. cssClassName: A string representing the CSS class. Example:

window.setCSSClass('custom-popup-style')  // Apply a custom CSS class to style the window

Brings the window to the front of other windows. Example:

window.toFront();  // Bring the window to the front

Moves the window behind all other windows. Example:

window.toBack();  // Move the window behind other windows

Hides the window but keeps it in memory so that it can be shown again. Example:

window.hide();  // Hide the window

Permanently closes the window and removes it from memory. Once destroyed, the window cannot be reopened without recreating it. Example:

window.destroy();  // Close and remove the window

Example: Creating and Customizing a Window

/**
 * Create and customize a window to display a form.
 */
function openCustomWindow() {
    //  Create the window with a unique name and type (e.g., a non-modal dialog)
    var win = application.createWindow('customWindow', JSWindow.DIALOG);

    //  Set the title of the window
    win.title = 'Custom Popup Window';

    //  Set the size of the window to 500px wide and 400px tall
    win.setSize(500, 400);

    //  Set the position of the window at (200px, 150px) on the screen
    win.setLocation(200, 150);

    // Set the window to be undecorated (no title bar or borders)
    win.undecorated = false;  // Set to true to hide title bar and borders if needed

    // Set the window to be non-resizable
    win.resizable = false;

    // Set the opacity to 80% (slightly transparent)
    win.opacity = 0.8;

    // Apply a custom CSS class for styling in NG Client
    win.setCSSClass('custom-popup-style');  // Use your custom CSS class for styling

    // Display the form inside the window
    win.show(forms.customForm);  // Replace 'customForm' with the form you want to display
}

Customizing the Window Further: You can further customize the CSS class applied to the window using styles defined in a custom CSS file. For example:

.custom-popup-style {
    background-color: rgba(255, 255, 255, 0.9);  /* Slightly transparent white background */
    border: 2px solid #007BFF;  /* Blue border */
    border-radius: 8px;  /* Rounded corners */
}

Undecorated Windows: If you want a minimalistic window (without title bar and borders), set win.undecorated = true. This can be useful for creating popups that don't need window controls.

Accessing an Existing Window

If you need to access an existing window that was previously created, you can use application.getWindow to retrieve it by name.

Example:

/**
 * Access an existing window and modify its properties.
 */
function modifyExistingWindow() {
    // Access the existing window by its name
    var win = application.getWindow('myDialog');
    
    if (win) {
        // Modify the window's properties
        win.setSize(500, 350);
        win.setTitle('Updated Window Title');
    } else {
        application.output('Window not found.');
    }
}

Dialog Types

In Servoy, when you create a window (such as a dialog) using the application.createWindow method, you can specify whether the dialog is modal or non-modal. Understanding the difference between these two dialog types is crucial for controlling user interaction with your application.

A modal dialog is a type of window that requires the user to interact with it before they can return to the parent window or any other window in the application. While the modal dialog is open, the user is blocked from interacting with other parts of the application until the modal dialog is closed.

Key Characteristics of Modal Dialogs:

  • Blocking: The user must dismiss (e.g., close, submit) the modal dialog before returning to the parent window.

  • Use Cases: Modal dialogs are typically used when you need to gather important input from the user, confirm an action, or display critical information that must be addressed before proceeding.

  • Example: A "Save Changes?" confirmation dialog when closing an unsaved document.

Creating a Modal Dialog in Servoy: You can create a modal dialog using the JSWindow.MODAL_DIALOG constant with the application.createWindow method.

Example: Creating a Modal Dialog

/**
 * Open a modal dialog window to display a form.
 */
function openModalDialog() {
    // Create a modal dialog window
    var modalWindow = application.createWindow('myModalDialog', JSWindow.MODAL_DIALOG);
    
    // Set window properties
    modalWindow.title = 'Confirmation Dialog';
    modalWindow.setSize(400, 200);  // Set the size of the window
    modalWindow.setLocation(300, 150);  // Set the position of the window
    
    // Display a form inside the modal dialog
    modalWindow.show(forms.confirmationForm);  // Replace with the form you want to display
}

In this example:

  • JSWindow.MODAL_DIALOG creates a modal dialog window, blocking interaction with the rest of the application until the user closes it.

  • The form confirmationForm is displayed inside the modal window.

Non-Modal Dialogs

A non-modal dialog is a window that allows the user to interact with other parts of the application while the dialog remains open. The user is free to switch between the dialog and the parent window without being forced to close the dialog first.

Key Characteristics of Non-Modal Dialogs:

  • Non-blocking: The user can interact with other windows or forms while the dialog remains open.

  • Use Cases: Non-modal dialogs are used when the user might need to refer back to other parts of the application while interacting with the dialog, such as displaying help text, additional settings, or tools that can be used alongside the main form.

  • Example: A floating "Find & Replace" tool in a text editor that remains open while you edit the document.

Creating a Non-Modal Dialog in Servoy: You can create a non-modal dialog using the JSWindow.DIALOG constant.

Example: Creating a Non-Modal Dialog

/**
 * Open a non-modal dialog window to display a form.
 */
function openNonModalDialog() {
    // Create a non-modal dialog window
    var nonModalWindow = application.createWindow('myNonModalDialog', JSWindow.DIALOG);
    
    // Set window properties
    nonModalWindow.title = 'Help Dialog';
    nonModalWindow.setSize(500, 300);  // Set the size of the window
    nonModalWindow.setLocation(100, 100);  // Set the position of the window
    
    // Display a form inside the non-modal dialog
    nonModalWindow.show(forms.helpForm);  // Replace with the form you want to display
}

In this example:

  • JSWindow.DIALOG creates a non-modal dialog window that allows the user to interact with both the dialog and the rest of the application simultaneously.

  • The form helpForm is displayed inside the non-modal dialog window.

Differences Between Modal and Non-Modal Dialogs

The main difference between modal and non-modal dialogs lies in how they handle user interaction with the rest of the application. A modal dialog blocks the user from interacting with other windows or parts of the application while the dialog is open. This means that the user must address the dialog—either by providing input, confirming an action, or dismissing it—before they can return to the main window. Modal dialogs are commonly used when you need to ensure the user’s attention and interaction with the dialog content before proceeding, such as when confirming a critical action or requiring immediate user input.

On the other hand, a non-modal dialog allows the user to continue interacting with other parts of the application even while the dialog remains open. Non-modal dialogs are designed to be auxiliary, meaning the user can freely switch between the dialog and other windows without being forced to close the dialog first. These types of dialogs are useful for displaying supplementary information or providing tools that assist the user without interrupting their workflow. For example, a help window or a settings panel can remain open while the user continues to interact with the main application.

In summary, a modal dialog demands the user’s attention by blocking access to other parts of the application, while a non-modal dialog is more flexible, allowing the user to interact with both the dialog and other windows simultaneously.

Pop-ups

A popup in Servoy refers to a small, temporary window or menu that appears over the main application, usually triggered by a user action such as a button click or right-click. Popups can provide additional information, display options, or allow users to make a quick selection without leaving the current window. Popups can take different forms, including context menus, tooltip-like messages, or dialog windows.

Popups are useful when you want to provide a concise, focused interaction without requiring a full screen or form switch. They are often used for showing contextual actions (like right-click menus), alerts, or quick forms for user input.

Characteristics of Popups:

  • Non-blocking: Users can interact with the rest of the application while the popup is open.

  • Temporary: Popups usually appear in response to a specific user action (such as a right-click or button click) and disappear after the action is completed.

  • Lightweight: Popups are often used to present small bits of information or quick actions (such as a context menu or a small input form).

  • Positioned: Popups are generally positioned near the element or event that triggered them, such as near a button click or mouse location.

Use Cases for Popups:

  • Context Menus: A right-click menu with a list of actions.

  • Quick Actions: Dropdowns or simple action selections related to a specific context.

  • Input Forms: Collecting simple data without navigating away from the main interface.

Creating a Popup Using plugins.window.createFormPopup()

The plugins.window.createFormPopup() method is used to create a popup window that can display an entire form. This is useful when you want to display more complex content, such as input fields, lists, or detailed information, in a compact popup window that doesn’t interrupt the user’s flow.

Example: Using plugins.window.createFormPopup()

/**
 * Create and display a popup form using plugins.window.createFormPopup().
 * This popup form is used for showing detailed information or gathering user input.
 */
function showPopupForm(event) {
    // Create a form popup and display the 'popupForm' form inside it
    var popup = plugins.window.createFormPopup(forms.popupForm);

    // Customize the popup: set its size, position
      popup.width(300) // Set the width of the popup window
      popup.height(200) // Set the height of the popup window
      popup.setLocation(event.getX(), event.getY())  // Position the popup near the mouse click
      popup.x(event.getX())  // Position the popup near the mouse click
      popup.y(event.getY())  // Position the popup near the mouse click
      popup.show();  // Show the popup
}

How It Works:

  • createFormPopup(forms.popupForm) creates a popup window that contains the popupForm form..

  • popup.show() displays the popup with the specified form.

Creating a Popup Menu Using plugins.window.createPopupMenu()

The plugins.window.createPopupMenu() method is used to create contextual popup menus. These popups display a list of options or actions related to the current context, such as right-click menus or dropdown-style menus. It's a lightweight solution for offering quick actions.

Example: Using plugins.window.createPopupMenu()

/**
 * Show a popup menu using plugins.window.createPopupMenu(), triggered by a right-click or button click.
 */
function showPopupMenu(event) {
    // Create a popup menu object
    var popupMenu = plugins.window.createPopupMenu();
    
    // Add menu items
    popupMenu.addMenuItem('Option 1', onOptionSelected);
    popupMenu.addMenuItem('Option 2', onOptionSelected);
    popupMenu.addMenuItem('Option 3', onOptionSelected);

    // Show the popup menu at the location of the event
    popupMenu.show(event.getSource());
}

/**
 * Handle the selection from the popup menu.
 * @param {JSEvent} event - The event object associated with the selection.
 */
function onOptionSelected(event) {
    var selectedText = event.getSource().text;
    application.output('You selected: ' + selectedText);
}

How It Works:

  • plugins.window.createPopupMenu() creates a popup menu object.

  • popupMenu.addMenuItem() adds individual menu items to the popup. Each menu item can have a callback function (in this case, onOptionSelected) that is triggered when the user selects that option.

  • popupMenu.show() displays the popup menu at the specified location, which is the source of the event (usually the location of the mouse click or right-click).

Differences Between createFormPopup() and createPopupMenu()

Purpose:

  • createFormPopup() is used for showing entire forms within a popup. It is ideal when you need to display complex content, such as data input fields, buttons, or even grids, in a popup window.

  • createPopupMenu() is designed for displaying contextual menus, offering a quick list of action options related to the user's interaction (e.g., right-click menus or dropdowns).

Content:

  • createFormPopup() allows you to display a full Servoy form with various UI components, enabling complex user interactions like input forms, detailed information, or interactive grids.

  • createPopupMenu() is focused on displaying a simple list of menu options for users to select from. It's lightweight and meant for quick, action-oriented interactions.

Interaction:

  • createFormPopup() provides the ability to collect complex input or show detailed content in a popup. For example, you could display a small form for entering details without navigating away from the current screen.

  • createPopupMenu() is designed for quick, one-click actions where users select from a small list of options. It’s commonly used for context menus, dropdowns, or quick settings.

Use Cases:

  • createFormPopup() is useful when you need to display detailed content or gather user input in a non-intrusive, temporary window. For example, you might use it to display additional details about an item in a list or a small form for entering information without switching screens.

  • createPopupMenu() is best for providing quick options or context menus based on the user’s interaction, such as when a user right-clicks on a record to edit, delete, or view details.

Differences Between Popups and Dialogs

Popups and dialogs in Servoy serve different purposes. Popups are non-blocking, lightweight, and ideal for quick actions or contextual menus, while dialogs are used for more complex interactions, often requiring the user's full attention, especially when modal. By understanding the differences and use cases, you can choose the appropriate method for user interaction in your application.

Key Differences Between Popups and Dialogs:

  • Interaction:

    • Popups: Non-blocking. The user can continue interacting with other parts of the application while the popup is open.

    • Dialogs: Modal dialogs block user interaction with the rest of the application until the dialog is closed. Non-modal dialogs allow interaction with other parts of the application, but dialogs are generally more attention-demanding.

  • Complexity:

    • Popups: Lightweight and used for simple, quick actions like context menus, option selections, or brief information.

    • Dialogs: More comprehensive and used for more complex tasks like data input, confirmations, or detailed forms.

  • Blocking Behavior:

    • Popups: Do not block the user’s ability to interact with the main application.

    • Dialogs: Modal dialogs require the user to take action (e.g., confirm, cancel) before returning to the main application.

  • Content:

    • Popups: Typically contain menus, quick input fields, or small bits of information.

    • Dialogs: Can hold detailed forms, user confirmations, critical messages, or more complex interactions that require focus.

  • Appearance:

    • Popups: Often smaller, positioned near the triggering action (such as near a button or mouse click).

    • Dialogs: Usually larger and centered on the screen, appearing as a distinct window with title bars and borders (if not undecorated).

When to Use Each:

  • Use a Popup when you need to provide a quick, lightweight option or show contextual actions in response to a user event (such as a right-click or a button click).

  • Use a Dialog when you need to block the user's attention or gather important input that requires more focus, such as confirmations or filling out detailed forms. Modal dialogs are especially useful for critical actions like deletions or data validation.

Patterns: Choosing Between Dialogs, Forms, and Pop-ups

Dialogs Plugin

The dialogs plugin in Servoy is useful for showing simple blocking dialogs, such as confirmations or alerts. This plugin is typically used for simple choices where script-blocking behavior is required. You can find here more information about Dialogs Plugin.

Use Case: Showing a Yes/No confirmation dialog.

Example:

var result = plugins.dialogs.showQuestionDialog('Confirm', 'Do you wish to proceed?', 'Yes', 'No');
if (result == 'Yes') {
    // Proceed with action
}

Form-in-Dialog

A Form-in-Dialog in Servoy refers to the concept of displaying a form inside a dialog window. This allows developers to present an entire form within a modal or non-modal popup, enabling users to interact with the form without navigating away from the main application window.

Key Features of Form-in-Dialog:

  • Encapsulation of Forms: Any form in Servoy can be opened as a dialog. It is displayed in a separate window but retains all its usual form components like text fields, buttons, grids, and logic. The form in the dialog behaves just like a regular form, but it is presented in a pop-up window.

  • Modal and Non-Modal: The dialog can be either modal or non-modal:

    • Modal: When opened as a modal dialog, it blocks interaction with the rest of the application until the user interacts with and closes the dialog.

    • Non-Modal: When opened as a non-modal dialog, users can still interact with the rest of the application while the dialog remains open.

  • Customizable Size and Position: Dialog windows are customizable in terms of size, position, and appearance (e.g., title bar, borders). Developers can define how large the dialog is and where it appears on the screen.

  • Reusability: Forms used in dialogs can be reused throughout the application. For example, a single form for adding/editing records can be used as a dialog whenever required.

  • Interaction with Calling Form: The form in the dialog can return values back to the calling form, enabling communication between the dialog and the main form. This is useful for confirming user actions, gathering input, or performing some task within the dialog.

Typical Use Cases:

  • Confirmation Dialog: A common use case for a Form-in-Dialog is when the application requires confirmation from the user before proceeding with a critical action, such as deleting a record or submitting a form. The modal dialog ensures that the user’s attention is focused on the confirmation request, preventing interaction with the rest of the application until the user responds.

  • Data Entry or Editing: Form-in-Dialog can be used to display a form that allows users to input or edit data. This is useful when you want to keep the main screen clean while presenting a focused input form in a popup dialog.

  • Displaying Detailed Information: A non-modal Form-in-Dialog can be used to display detailed information about a record or item without leaving the current screen. This allows users to interact with the additional information while still having access to the main form.

  • Wizard or Multi-Step Forms: When creating a multi-step form or wizard, you can use a Form-in-Dialog to guide users through different steps of a process without taking them away from the main interface.

  • Returning Data to the Main Form: A modal dialog can return data to the form that opened it. This is useful when gathering specific input from the user and returning the value to the main workflow for further processing.

  • Non-Intrusive Help or Information: You can use a non-modal Form-in-Dialog to display help content or additional instructions without blocking the main workflow.

How to Create a Form-in-Dialog in Servoy

To create a form in a dialog, you use the application.createWindow method, which generates a new window to display the form.

Example: Creating a Modal Form-in-Dialog

/**
 * Function to open a modal dialog displaying 'myDialogForm'.
 */
function openModalFormDialog() {
    // Create a modal dialog window
    var dialog = application.createWindow('myDialog', JSWindow.MODAL_DIALOG);
    
    // Set the dialog window properties
    dialog.title = 'My Dialog Form';
    dialog.setSize(400, 300);  // Set the size of the window
    dialog.setLocation(200, 150);  // Position the window on the screen
    
    // Show the 'myDialogForm' inside the modal dialog window
    dialog.show(forms.myDialogForm);
}

Example: Creating a Non-Modal Form-in-Dialog

/**
 * Function to open a non-modal dialog displaying 'myNonModalForm'.
 */
function openNonModalFormDialog() {
    // Create a non-modal dialog window
    var dialog = application.createWindow('nonModalDialog', JSWindow.DIALOG);
    
    // Set the dialog window properties
    dialog.title = 'Non-Modal Form';
    dialog.setSize(500, 400);  // Set the window size
    dialog.setLocation(300, 200);  // Position the window
    
    // Show the form 'myNonModalForm' inside the non-modal dialog
    dialog.show(forms.myNonModalForm);
}

Handling Dialog Events (onShow, onHide, etc.)

When a form is opened in a dialog, the form's events such as onShow, onHide, and others will still execute. This allows you to add logic that triggers when the form is shown or hidden.

  • onShow: Fired when the form is displayed inside the dialog.

  • onHide: Fired when the form is closed or hidden.

Example: Using onShow Event

function onShow(firstShow, e