Skip to the main content

Dialogs and the image viewer (shared by the Modal, Image, Gallery and video modules)

Several Webal modules open something on top of the page: the Modal opens a dialog with text, an article or a module position; the Image and Gallery modules open a picture in a full-window viewer with Previous and Next. They all use the same dialog, so they all behave the same way. This page says what visitors get and what you can rely on. The options of each module (the trigger, the size, the text) are on that module's own page.

What a visitor gets

  • A real dialog. The page behind it cannot be reached with the keyboard, the mouse or a screen reader while it is open. Tab stays inside the dialog and goes round.
  • Focus is looked after. When it opens, focus lands on the Close button (or on the title, for a dialog that starts with a long text). When it closes, by any route, focus goes back to the button or picture link that opened it.
  • Every way out works. The Close button, the Escape key, a click outside the dialog (unless the module says Escape and buttons only), an OK button that closes the dialog, and a link inside the dialog that goes to the page you are already on.
  • One at a time. A second dialog cannot be opened on top of the first, and a dialog written inside another dialog is left out.
  • Never a trap. A dialog is not opened if the place it sits in is not drawn (a Module Class such as d-none d-lg-block, a closed menu panel, a closed accordion): it would freeze the page with nothing to see. Put the module where it is shown, and use the module's own Visibility option. A place hidden only with visibility: hidden does let the dialog open, and the dialog is drawn. A dialog is also never opened if it has no real Close button (a button with the Close command, not a lookalike) or if Escape would not close it. A button that opens a dialog, and the Close button in it, act on the dialog of their own module even when another element with the same id was printed earlier on the page.
  • The page does not jump. While the dialog is open the page behind does not scroll and does not shift sideways when its scrollbar goes. The scroll position is kept.
  • It is named. The dialog has a heading, which is its name for a screen reader. The Close button, Previous and Next have text names, not just icons, and all of them are at least 44 pixels square.
  • Motion is gentle and optional. The dialog fades in and rises a little. Someone who has asked their device for less motion gets none.
  • It works in Windows high contrast and right to left. Borders stay visible in forced colours; in a right-to-left language the header, the buttons and the arrows are mirrored, and the arrow keys follow what is on screen.

Without JavaScript

If scripts do not run (blocked, broken, or a very old browser):

  • A dialog is shown in the page, under its heading, and its button and Close button are hidden. Nothing is lost: the text is just there.
  • A picture is a plain link to the full image. It opens the image by itself, as any link does.

The image viewer

  • Click a picture and the viewer opens at that picture, on a dark full-window background, with the picture's text description, its caption, and "3 of 12".
  • Previous and Next buttons, or the Left and Right arrow keys, move through the set and wrap round at both ends. A set of one picture shows no buttons and no count.
  • The set is what is visible when the viewer opens, in the order on the page. A picture hidden by a filter is skipped, and the count follows.
  • The full-size picture is only fetched when the viewer opens (and the next one is prepared). The small pictures on the page stay small.
  • A screen reader hears the position and the picture's description each time you move ("4 of 12: Rose garden"). Captions are plain text: a link or a tag in a caption is shown as typed.
  • Ctrl, Shift, Alt, Cmd and middle click are left to the browser, so "open in a new tab" still works.
  • A picture that cannot be loaded shows "This image could not be loaded."

Things to know

  • The page behind is not reachable. If a dialog holds a form, the visitor must finish or close it before anything else on the page works. Keep dialogs short.
  • Dialogs are not for the page's main content. Without JavaScript they sit in the page, so anything essential should also make sense there.
  • Older browsers. Internet Explorer is not supported. Browsers that lack the newest dialog features (Firefox before 144 and Safari before 26.2 for the "command" button, Firefox before 141 and Safari for clicking outside to close, Firefox before 133 and Safari before 26 for the "about to open" event) get a small script that does the same job, and it is tested in Chrome with those features switched off. It has not yet been run in a real Safari or Firefox: the first real-browser check is owed (Phase 4), so treat the older versions as expected to work, not as proven.
  • Text from articles inside a dialog is shown, but it does not run Alpine: the dialog's own script is attached to a hidden marker in its header, not around the content, so attributes such as x-bind in article HTML do nothing.
  • The scrollbar fix pads the page by the width of the scrollbar that disappears. A scrollbar on the left (some systems in right-to-left languages) is handled too, but has not been tried on a real left-hand scrollbar yet.