ModalDialog

The ModalDialog component defines a modal dialog UI element that can be displayed over the existing UI - triggered by some action.

The component provides context values with which you can access some internal properties:

• $param: This value represents the first parameters passed to the open() method to display the modal dialog.
• $params: This value represents the array of parameters passed to the open() method. You can use $params[0] to access the first and $params[1] to access the second (and so on) parameters. $param is the same as $params[0].

Using the Component

Opening and closing the modal dialog can be done in two ways depending on circumstances.

With Imperative API

Event-driven display of the ModalDialog dialog is also possible using imperative API.

This method is a good way to toggle the display of the ModalDialog if no deep linking is necessary. It also lends to itself that these events can be triggered programmatically from codebehind.

Note the id property of the ModalDialog in the example below and how it is used to call the open and close operations of the component in the onClick event handlers.

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Dialog">
    <Button label="Close Dialog" onClick="dialog.close()" />
  </ModalDialog>
</App>

With when

The when property accepts a primitive boolean or a binding expression resolving to a boolean value to toggle the display of a component.

Using the when property in a ModalDialog dialog component is commonly used with deep linking: showing the modal in conjunction with an updated URL so that the opened state of the modal dialog is referable.

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <variable name="isDialogShown" value="{false}"/>
  <Button label="Open Dialog" onClick="isDialogShown = true" />
  <ModalDialog 
    when="{isDialogShown}" 
    title="Example Dialog" 
    onClose="isDialogShown = false" />
</App>

Click on the button in the demo below to open the modal dialog. Click anywhere outside the opened dialog or the close button to close it.

Setting the when property is the most straightforward way for deep-linked modals. If you use deep links with query parameters to show a particular dialog, you can set the when property to show or hide the dialog according to parameter values.

The ModalDialog as a Container

The ModalDialog component is also a container such as the Card, that it also accepts child components.

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Dialog">
    <Form data="{{ firstName: 'Billy', lastName: 'Bob' }}">
      <FormItem bindTo="firstName" required="true" />
      <FormItem bindTo="lastName" required="true" />
    </Form>
  </ModalDialog>
</App>

Properties

closeButtonVisible (default: true)

Shows (true) or hides (false) the visibility of the close button on the dialog.

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" closeButtonVisible="false" title="Example Dialog" />
</App>

Click outside the dialog to close it.

fullScreen (default: false)

Toggles whether the dialog encompasses the whole UI (true) or not and has a minimum width and height (false).

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" fullScreen="true" title="Example Dialog" />
</App>

Click the button to display a full-screen dialog. The icon at the top-right corner of the dialog allows you to close it.

title

Provides a prestyled heading to display the intent of the dialog.

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="dialog.open()" />
  <ModalDialog id="dialog" title="Example Title" />
</App>

Events

close

This event is fired when the close button is pressed or the user clicks outside the ModalDialog.

In this example, the close event counts how many times you closed the dialog:

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onClose="counter++">
    <Text value="Dialog closed {counter} number of times." />
  </ModalDialog>
</App>

Open and close the dialog several times to test that it changes the counter.

open

This event is fired when the ModalDialog is opened either via a when or an imperative API call (open()).

In this example, the open event counts how many times you opened the dialog:

<App height="100%" verticalAlignment="center" horizontalAlignment="center">
  <Button label="Open Dialog" onClick="myDialog.open()" />
  <ModalDialog
    id="myDialog"
    title="Example Dialog"
    var.counter="{0}"
    onOpen="counter++">
    <Text value="Dialog opened {counter} number of times." />
  </ModalDialog>
</App>

Open and close the dialog several times to test that it changes the counter.

Exposed Methods

close

This method is used to close the ModalDialog. Invoke it using modalId.close() where modalId refers to a ModalDialog component.

See the `With Imperative API` subsection for an example.

open

This method imperatively opens the modal dialog. You can pass an arbitrary number of parameters to the method. In the ModalDialog instance, you can access those with the $paramq and $params context values.

See the `With Imperative API` subsection for an example.

Styling

The ModalDialog component uses these theme variables to customize its appearance:

• backgroundColor
• backgroundColor-overlay
• color
• fontFamily
• height
• marginBottom-title
• marginTop,
• maxWidth
• minWidth
• padding (including all padding variants, such as paddingLeft and others)
• padding-overlay (including all padding variants, such as paddingLeft and others)
• borderRadius

Theme Variables