Skip to main content
Light Dark System

Dialog

<et2-dialog> | Et2Dialog
Since 23.1

Overview

A common dialog widget that makes it easy to inform users or prompt for information.

It is possible to have a custom dialog by using a template, but you can also use the static method Et2Dialog.show_dialog(). At its simplest, you can just use:

Et2Dialog.show_dialog(false, "Operation completed");

Or a more complete example:

let callback = function (button_id)
{
	if(button_id == Et2Dialog.YES_BUTTON)
	{
		// Do stuff
	}
	else if (button_id == Et2Dialog.NO_BUTTON)
	{
		// Other stuff
	}
	else if (button_id == Et2Dialog.CANCEL_BUTTON)
	{
		// Abort
	}
}.
let dialog = Et2Dialog.show_dialog(
	callback, "Erase the entire database?","Break things", {} // value
	et2_dialog.BUTTONS_YES_NO_CANCEL, et2_dialog.WARNING_MESSAGE
);

Or, using Promises instead of a callback:

let result = await Et2Dialog.show_prompt(null, "Name").getComplete();
if(result.button_id == Et2Dialog.OK_BUTTON)
{
    // Do stuff with result.value
}

The parameters for the above are all optional, except callback (which can be null) and message:

  • callback - function called when the dialog closes, or false/null. The ID of the button will be passed. Button ID will be one of the Et2Dialog.*_BUTTON constants. The callback is not called if the user closes the dialog with the X in the corner, or presses ESC.
  • message - (plain) text to display
  • title - Dialog title
  • value (for prompt)
  • buttons - Et2Dialog BUTTONS_* constant, or an array of button settings. Use DialogButton interface.
  • dialog_type - Et2Dialog *_MESSAGE constant
  • icon - URL of icon

Note that these methods will not block program flow while waiting for user input unless you use “await” on getComplete(). The user’s input will be provided to the callback.

You can also create a custom dialog using an etemplate, even setting all the buttons yourself.

// Pass egw in the constructor
	let dialog = new Et2Dialog(my_egw_reference);

	// Set attributes.  They can be set in any way, but this is convenient.
	dialog.transformAttributes({
		// If you use a template, the second parameter will be the value of the template, as if it were submitted.
		callback: function(button_id, value) {...},	// return false to prevent dialog closing
		buttons: [
			// These ones will use the callback, just like normal.  Use DialogButton interface.
			{label: egw.lang("OK"),id:"OK", default: true},
			{label: egw.lang("Yes"),id:"Yes"},
			{label: egw.lang("Sure"),id:"Sure"},
			{label: egw.lang("Maybe"),click: function() {
				// If you override, 'this' will be the dialog DOMNode.
				// Things get more complicated.
				// Do what you like here
			}},

		],
		title: 'Why would you want to do this?',
		template:"/egroupware/addressbook/templates/default/edit.xet",
		value: { content: {...default values}, sel_options: {...}...}
	});
// Add to DOM, dialog will auto-open
document.body.appendChild(dialog);
// If you want, wait for close
let result = await dialog.getComplete();

Customize initial focus by setting the “autofocus” attribute on a control, otherwise first input will have focus

Properties

Name Description Reflects Type Default
accesskey Accesskey provides a hint for generating a keyboard shortcut for the current element. The attribute value must consist of a single printable character. string -
align Used by Et2Box to determine alignment. Allowed values are left, right string -
appendTo Legacy-option for appending dialog into a specific dom node - -
buttons Pre-defined group of buttons, one of the BUTTONS_* - -
class CSS Class. This class is applied to the outside, on the web component itself. Due to how WebComponents work, this might not change anything inside the component. string -
data Set the dataset from a CSV string -
deferredProperties
Any attribute that refers to row content cannot be resolved immediately, but some like booleans cannot stay a string because it’s a boolean attribute. We store them for later, and parse when they’re fully in their row. If you are creating a widget that can go in a nextmatch row, and it has boolean attributes that can change for each row, add those attributes into deferredProperties - -
destroyOnClose Automatically destroy the dialog when it closes. Set to false to keep the dialog around. boolean true
disabled Defines whether this widget is visibly disabled. The widget is still visible, but clearly cannot be interacted with. Widgets disabled in the template will not return a value to the application code, even if re-enabled via javascript before submitting. To allow a disabled widget to be re-enabled and return a value, disable via javascript in the app’s et2_ready() instead of an attribute in the template file. boolean false
dom_id
Get the actual DOM ID, which has been prefixed to make sure it’s unique. string -
hidden The widget is not visible. As far as the user is concerned, the widget does not exist. Widgets hidden with an attribute in the template may not be created in the DOM, and will not return a value. Widgets can be hidden after creation, and they may return a value if hidden this way. boolean -
hideOnEscape When it’s set to false dialog won’t get closed by hitting Esc - -
id
Get the ID of the widget string -
isModal Allow other controls to be accessed while the dialog is visible while not conflicting with internal attribute boolean false
label The label of the widget This is usually displayed in some way. It’s also important for accessability. This is defined in the parent somewhere, and re-defining it causes labels to disappear string -
modal
Exposes the internal modal utility that controls focus trapping. To temporarily disable focus trapping and allow third-party modals spawned from an active Shoelace modal, call modal.activateExternal() when the third-party modal opens. Upon closing, call modal.deactivateExternal() to restore Shoelace’s focus trapping. - new Modal(this)
noCloseButton When set to true it removes the close button from dialog’s header boolean -
noHeader
no-header
Disables the header. This will also remove the default close button, so please ensure you provide an easy, accessible way for users to dismiss the dialog. boolean false
noLang Disable any translations for the widget boolean -
open Indicates whether or not the dialog is open. You can toggle this attribute to show and hide the dialog, or you can use the show() and hide() methods and this attribute will reflect the dialog’s open state. boolean false
parentId Parent is different than what is specified in the template / hierarchy. Widget ID of another node to insert this node into instead of the normal location string -
PLAIN_MESSAGE
Types number 0
statustext Tooltip which is shown for this element on hover string -
styles
WebComponent * - -
template Instead of a message, show this template file instead - -
title Title for the dialog, goes in the header string -
value Returns the values of any widgets in the dialog. This does not include the buttons, which are only supplied for the callback. Object -
options
Get property-values as object
use widget methods
object -
supportedWidgetClasses
et2_widget compatability
Legacy compatability. Some legacy widgets check their parent to see whats allowed
array []
updateComplete A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name React Event Description Event Detail
open EVENT NEEDS A DESCRIPTION Event
close EVENT NEEDS A DESCRIPTION Event
before-load EVENT NEEDS A DESCRIPTION CustomEvent

Learn more about events.

Methods

Name Description Arguments
alert() Show an alert message with OK button _message: string, _title: string, _type: integer
checkCreateNamespace() Checks whether a namespace exists for this element in the content array. If yes, an own perspective of the content array is created. If not, the parent content manager is used. Constructor attributes are passed in case a child needs to make decisions -
clone() Creates a copy of this widget. _parent: et2_widget
close() Hide the dialog. Depending on destroyOnClose, it may be removed as well N.B. We can’t have open() because it conflicts with SlDialog. Use show() instead. -
confirm() Method to build a confirmation dialog only with YES OR NO buttons and submit content back to server _senders: widget, _dialogMsg: string, _titleMsg: string, _postSubmit: boolean
createElementFromNode() Create a et2_widget from an XML node. First the type and attributes are read from the node. Then the readonly & modifications arrays are checked for changes specific to the loaded data. Then the appropriate constructor is called. After the constructor returns, the widget has a chance to further initialize itself from the XML node when the widget’s loadFromXML() method is called with the node. _node: , _name:
getArrayMgr() Returns the array manager object for the given part managed_array_type: string
getArrayMgrs() Returns an associative array containing the top-most array managers. _mgrs: object
getChildren() Get child widgets Use .children to get web component children -
getInstanceManager() Returns the instance manager -
getPath() Returns the path into the data array. By default, array manager takes care of this, but some extensions need to override this -
getRoot() Returns the base widget Usually this is the same as getInstanceManager().widgetContainer -
hide() Hides the dialog -
loadFromXML() Loads the widget tree from an XML node _node:
loadingFinished() Needed for legacy compatability. promises: Promise[]
long_task() Show a dialog for a long-running, multi-part task Given a server url and a list of parameters, this will open a dialog with a progress bar, asynchronously call the url with each parameter, and update the progress bar. Any output from the server will be displayed in a box. When all tasks are done, the callback will be called with boolean true. It will also be called if the user clicks a button (OK or CANCEL), so be sure to check to avoid executing more than intended. _callback: function, _message: string, _title: string, _menuaction: string, _list: Array[], _egw_or_appname: string|egw
parseXMLAttrs() The parseXMLAttrs function takes an XML DOM attributes object and adds the given attributes to the _target associative array. This function also parses the legacyOptions. N.B. This is only used for legacy widgets. WebComponents use transformAttributes() and do their own handling of attributes. _attrsObj: , _target: object, _proto: et2_widget
set_label() NOT the setter, since we cannot add to the DOM before connectedCallback() TODO: This is not best practice. Should just set property, DOM modification should be done in render https://lit-element.polymer-project.org/guide/templates#design-a-performant-template value: string
setArrayMgr() Sets the array manager for the given part _part: string, _mgr: object
setArrayMgrs() Sets all array manager objects - this function can be used to set the root array managers of the container object. _mgrs: object
setInstanceManager() Set the instance manager Normally this is not needed as it’s set on the top-level container, and we just return that reference manager: etemplate2
show() Shows the dialog. -
show_dialog() Show a confirmation dialog _callback: function, _message: string, _title: string, _value: object, _buttons: integer|array, _type: integer, _icon: string, _egw_or_appname: string|egw
show_prompt() Show a prompt dialog _callback: function, _message: string, _title: string, _value: string, _buttons: integer|array, _egw_or_appname: string|egw
updated() A property has changed, and we want to make adjustments to other things based on that changedProperties: PropertyValues
_adoptTemplateButtons() Search for buttons in the template, and try to slot them We don’t want to just grab them all, as there may be other buttons. -
_handleClick() Click handler calling custom handler set via onclick attribute to this.onclick _ev: MouseEvent
_onButtonClick() Only internally do our onClick on buttons in the footer This calls _onClose() when the dialog is closed ev: MouseEvent
_onMoveResize() Handle moving and resizing event: InteractEvent
_set_label() Do some fancy stuff on the label, splitting it up if there’s a %s in it Normally called from updated(), the “normal” setter stuff has already been run before this is called. We only override our special cases (%s) because the normal label has been set by the parent value: string
_setApiInstance() Inject application specific egw object with loaded translations into the dialog _egw_or_appname: string|egw
_setDefaultAutofocus() Set autofocus on first input element if nothing has autofocus -
destroy() et2_widget compatability
true
-
set_class() Set the widget class
Use this.class or this.classList instead
new_class: string
set_disabled() Wrapper on this.disabled because legacy had it.
Use widget.disabled for visually disabled, widget.hidden for visually hidden. Widgets that are hidden from the server via attribute or $readonlys will not be created. Widgets that are disabled from the server will not return a value to the application code.
value: boolean
set_statustext() supports legacy set_statustext
use this.statustext
value: string

Learn more about methods.