ServoyCloudSupportSamplesOpen SourceCommunity

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.

title

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';

undecorated

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

setSize(width, height)

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

setLocation(x, y)

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

resizable

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

opacity

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)

setCSSClass(cssClassName)

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

toFront()

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

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

toBack()

Moves the window behind all other windows. Example:

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

hide()

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

window.hide();  // Hide the window

destroy()

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.

Modal Dialogs

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, event) {
    application.output('Dialog form has been shown.');
}

Returning Values from Form-in-Dialog

A modal dialog can return values back to the calling form. For example, you can have the dialog collect user input and return that input to the form that opened it. This is useful for tasks like confirming an action or gathering additional details.

Example: Returning Values from a Modal Dialog

/**
 * Open a dialog and return a value when the dialog is closed.
 */
function openModalWithReturnValue() {
    var dialog = application.createWindow('myDialog', JSWindow.MODAL_DIALOG);
    dialog.setSize(400, 300);
    dialog.show(forms.confirmationForm);
    
    // Get the value returned by the dialog form
    var userConfirmed = forms.confirmationForm.getValue();
    if (userConfirmed) {
        application.output('User confirmed the action.');
    } else {
        application.output('User canceled the action.');
    }
}

In this example, forms.confirmationForm.getValue() could return a boolean value representing the user’s decision (e.g., true for confirm, false for cancel).

Form-in-Window

A Form-in-Window in Servoy refers to displaying a form inside a separate window. Unlike a dialog (which can be modal or non-modal and tends to be smaller), a Form-in-Window opens a fully functional new window where users can interact with a form while continuing their tasks in the main application. This approach is useful when you need a distinct, independent space for interaction, especially when you don’t want to block the rest of the application or need to display large amounts of data.

Key Features of Form-in-Window:

  • Separate Window: A form is displayed in an independent window that can be moved, resized, and interacted with, separately from the main application window. The form inside the window can still contain all typical UI components, events, and logic like any regular form.

  • Resizable and Movable: Form-in-Window allows users to resize and move the window around their screen, providing flexibility in terms of interaction and layout.

  • Customizable Window Properties: The window's size, location, title, and appearance can be fully customized, making it ideal for larger forms or forms requiring more screen space than a typical dialog.

  • Interaction Between Windows: Forms in windows can interact with the calling form, passing values between windows and enabling dynamic updates across windows.

Typical Use Cases:

  • Displaying Detailed Data in a Separate Window: In applications where users work with detailed data or complex forms, Form-in-Window allows users to view and interact with that data in a separate window without disrupting their main workflow.

  • Complex User Interactions: For more complex interactions, like managing multi-step processes or wizards, Form-in-Window is a good choice. Users can complete one process in the window while leaving the main form untouched.

  • Non-Intrusive Data Display: In some cases, the user may need to access additional information, such as a help guide, report, or detailed data, without interrupting their workflow.

How to Create a Form-in-Window in Servoy

To open a form inside a window, you use application.createWindow to create a new window object, set its properties, and then display the form within that window.

Example: Creating a Form-in-Window

/**
 * Function to open a non-modal form in a new window.
 */
function openNonModalFormWindow() {
    // Create a non-modal window
    var window = application.createWindow('myWindow', JSWindow.WINDOW);
    
    // Set window properties
    window.title = 'Customer Details';
    window.setSize(600, 400);  // Set the size of the window
    window.setLocation(100, 100);  // Position the window on the screen
    
    // Display the 'customerDetailsForm' inside the non-modal window
    window.show(forms.customerDetailsForm);
}

Handling Events in Form-in-Window

Forms opened inside windows in Servoy will still trigger the usual form events like onShow, onHide, etc., allowing developers to handle actions such as preparing the form when it is displayed or saving data when the window is closed.

Example: Handling onShow Event

function onShow(firstShow, event) {
    application.output('Form has been shown in the window.');
}

Returning Data from a Window

Just like a Form-in-Dialog, a Form-in-Window can also return values back to the calling form. This is particularly useful when a modal window is used for collecting user input, and you want to pass the collected data back to the main form.

Example: Returning Values from a Window

/**
 * Open a modal window and return a value to the calling form.
 */
function openModalWithReturnValue() {
    var window = application.createWindow('returnValueWindow', JSWindow.WINDOW);
    window.setSize(400, 300);
    window.show(forms.inputForm);
    
    // Retrieve the value entered in the inputForm
    var enteredValue = forms.inputForm.getValue();
    application.output('User entered: ' + enteredValue);
}

Pop-ups

A Pop-up in Servoy refers to a temporary, lightweight window or form that provides contextual information or actions without disrupting the main user interface. Unlike dialogs or full windows, pop-ups are designed to be non-blocking and typically disappear when the user clicks outside of them. They are useful for showing quick actions, contextual options, or supplementary information near a particular element or location on the screen.

Key Features of a Pop-up:

  • Any Form Can Be Used as a Pop-up: Any Servoy form can be shown as a pop-up. This allows developers to reuse existing forms to display in pop-up windows, providing a flexible way to deliver content in a temporary, unobtrusive manner.

  • Non-Blocking Script: Pop-ups are non-blocking, meaning the rest of the application remains fully interactive while the pop-up is visible. Users can continue to interact with other parts of the application without needing to close the pop-up, making it ideal for quick actions or information.

  • Flexible Positioning: A pop-up can be displayed at specific x, y coordinates on the screen, or it can be positioned near a UI element (e.g., near a button or a mouse click). This flexibility allows you to present context-sensitive options exactly where the user is interacting.

  • Dismissed by Clicking Elsewhere: Pop-ups in Servoy automatically close when the user clicks anywhere outside the pop-up. This ensures that the pop-up remains unobtrusive and disappears when it is no longer needed.

  • Events on the Form Still Execute: Pop-ups in Servoy still trigger the usual form events, such as onShow and onHide, allowing you to handle custom logic when the pop-up is opened or closed.

Typical Use Cases:

  • Tooltip or Quick Info: Pop-ups can be used to display quick information or tooltips when the user hovers over or clicks on a UI element. This provides additional context or help without requiring a separate screen or modal dialog.

  • Quick Input: If you need the user to provide quick input, such as selecting from a few options or confirming an action, a pop-up is a great solution. Since pop-ups don’t block the main application, users can interact with them without interrupting their workflow.

  • Non-Intrusive Alerts: You can use pop-ups for non-intrusive alerts or notifications that need to be displayed temporarily without blocking the user's actions.

How to Create a Pop-up in Servoy

To create a pop-up, you can use plugins.window.createFormPopup() to display a form in a temporary pop-up window. This method allows you to define the form, size, and location of the pop-up.

Example: Creating a Pop-up Near an Element

/**
 * Function to open a pop-up form near a UI element.
 */
function showPopupNearElement(event) {
    // Create a pop-up form and display 'myPopupForm'
    var popup = plugins.window.createFormPopup(forms.myPopupForm);

    // Set pop-up properties: size and location near the clicked element
      popup.width(200) // Set the width of the popup window
      popup.height(150) // Set the height of the popup window
      popup.x(event.getX())  //Position the pop-up near the clicked element
      popup.y(event.getY())  // Position the pop-up near the clicked element
      popup.show();  // Show the pop-up
}

Example: Creating a Pop-up at Specific Coordinates

/**
 * Function to show a pop-up at specific screen coordinates.
 */
function showPopupAtCoordinates(x, y) {
    var popup = plugins.window.createFormPopup(forms.myPopupForm);
    
    // Set the size and the x,y coordinates of the pop-up
      popup.width(200) // Set the width of the popup window
      popup.height(150) // Set the height of the popup window
      popup.x(x)  // Set specific coordinates for the pop-up
      popup.y(y)  // Set specific coordinates for the pop-up
      popup.show();
}

Handling Events in Pop-ups

Even though pop-ups are lightweight and temporary, they still execute lifecycle events like onShow and onHide. These events allow you to perform any initialization when the pop-up is displayed and cleanup actions when it is hidden.

Example: Using onShow Event in a Pop-up

/**
 * Event triggered when the pop-up is shown.
 */
function onShow(firstShow, event) {
    application.output('Pop-up is now visible.');
}

  • onShow: Triggered when the pop-up is shown on the screen.

  • onHide: Triggered when the pop-up is closed, either because the user clicked elsewhere or the form was explicitly closed.

Automatically Closing Pop-ups

A key behavior of pop-ups is that they automatically close when the user clicks outside of the pop-up. This behavior makes pop-ups ideal for non-intrusive interactions, such as context menus or quick actions. This makes pop-ups a great choice for showing temporary information or actions that don’t require a dedicated dialog or window.

List Selection Popup or Popup Menu

A List Selection Popup or Popup Menu (non-form use) in Servoy is a lightweight, non-blocking popup that displays a list of options or actions, often used for context menus or dropdown-style selections. Unlike a Form-in-Popup, a list selection popup does not use a form; instead, it presents a list of items that the user can interact with. This kind of popup is ideal for quick actions, option selection, or contextual menus triggered by user interactions (like right-clicking or clicking on a button).

Key Features of a List Selection Popup or Popup Menu:

  • No Form Involved: Instead of showing a form, a list selection popup presents a list of actions or options directly. These are often displayed in response to user actions such as right-clicking on a record or selecting an item from a dropdown.

  • Non-Blocking Script: The popup menu is non-blocking, meaning the user can interact with other parts of the application while the menu is open. The application’s script continues to run in the background.

  • Custom Positioning: The popup menu can be displayed at a specific x, y coordinate on the screen or near the source element that triggered the popup (e.g., a button or table row). This flexibility is important for contextual menus and lists.

  • Closes Automatically: Like other popups, the list selection popup closes automatically when the user clicks anywhere outside of it or selects an option, making it a seamless and unobtrusive part of the user experience.

  • Simple Interaction: The popup menu is ideal for simple, quick interactions, such as selecting an action from a list (e.g., Edit, Delete, View Details). It’s commonly used for context menus or dropdown actions.

Typical Use Cases:

  • Context Menus: A common use case for a list selection popup is context menus, where users can right-click on an element (like a record in a table) to perform quick actions such as editing, deleting, or viewing details.

  • Dropdown or Option Selection: Popup menus are ideal for providing a list of options in a dropdown format. When a user clicks on a button, the popup menu displays the available options for the user to select from.

  • Quick Action Selection: Popups are perfect for quick action selection scenarios where the user needs to choose between several actions, such as in a toolbar or a grid. The popup menu presents the actions in a clean, non-intrusive way.

  • Simplified UI for Large Menus: When a form has many actions or options, displaying all of them directly on the screen can clutter the UI. A popup menu can provide a cleaner, more organized UI, showing only relevant options when needed.

How to Create a List Selection Popup or Popup Menu in Servoy

In Servoy, you can create a list selection popup or popup menu using plugins.window.createPopupMenu(). This method allows you to define menu items, set their callbacks, and display the popup near an element or at specific coordinates.

Example: Creating a Popup Menu Near an Element

/**
 * Function to show a popup menu with options near a UI element.
 */
function showPopupMenu(event) {
    // Create a popup menu
    var popupMenu = plugins.window.createPopupMenu();
    
    // Add items to the popup menu
    popupMenu.addMenuItem('Edit', onMenuItemClick);
    popupMenu.addMenuItem('Delete', onMenuItemClick);
    popupMenu.addMenuItem('View Details', onMenuItemClick);
    
    // Show the popup menu near the clicked element (e.g., a button or a table row)
    popupMenu.show(event.getSource());
}

/**
 * Callback function to handle menu item clicks.
 */
function onMenuItemClick(menuItem) {
    var selectedItem = menuItem.text;
    application.output('Selected option: ' + selectedItem);
    
    // Perform different actions based on the selected option
    if (selectedItem === 'Edit') {
        application.output('User selected to edit the item.');
    } else if (selectedItem === 'Delete') {
        application.output('User selected to delete the item.');
    } else if (selectedItem === 'View Details') {
        application.output('User selected to view details.');
    }
}

Explanation:

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

  • addMenuItem() adds individual items (e.g., Edit, Delete, View Details) to the popup menu. Each item can have a callback function to handle user selection.

  • popupMenu.show() displays the popup near the element that triggered the event (e.g., a button or table row).

Closing the Popup Menu Automatically

A list selection popup automatically closes when:

  • The user selects an option from the list.

  • The user clicks outside the popup.

This behavior ensures that the popup does not interfere with the user’s workflow and remains a temporary, lightweight interaction element.

Why Use One Type Over Another?

Dialogs: Should be used when critical user interaction is required, such as confirmations or actions that block the main UI workflow. Form-in-Dialog: Best suited for complex forms where you need full control of the form’s lifecycle, such as input forms that need to be validated before allowing a user to continue. Form-in-Window: Ideal for displaying large amounts of data or forms that need to remain open without blocking other windows. Pop-ups: Use pop-ups for quick, non-intrusive information or interaction. They are temporary and go away when the user interacts with the main window.

PreviousNavigationNextWorking with Data

Last updated