PrimeFaces Panels, Menus and Dialogs

Before the individual components, five facts explain almost every surprise in this family. All were observed.

They are Faces components with a JavaScript widget. Each component renders its markup and a script that creates a client object, a widget (PrimeFaces.cw("Panel","detailsPanel",{...}) in the page source). The widget is registered under the component’s widgetVar, which is generated (widget_f_details) unless you set it, and is reached from script with PF('detailsPanel'). That is how PF('editDialog').show() and PF('importPoll').stop() work. A widgetVar is a name in a global table, so give it a name that is unique in the page and does not equal the id of any element: the id of an element becomes a property of window, and a widget variable of the same name is a recipe for confusion (the examples use ids such as details with the widget variable detailsPanel).

The namespace is primefaces. PrimeFaces 16 declares the tag library as xmlns:p="primefaces" (the Faces 4.0 URN style) and keeps the older http://primefaces.org/ui working. Both are used in the wild; this section uses the short one.

Ajax defaults to process="@all". A p:commandButton, a p:menuitem or a p:poll without process posted jakarta.faces.partial.execute=@all in every request below, unlike f:ajax, whose default is @this (see execute and render). Row buttons that only need the row should say process="@this", otherwise every other input of the page is decoded, converted and validated for a click on one row.

update is resolved from the source component’s naming container. A p:accordionPanel with value/var, a p:dataTable, a ui:repeat and a p:tabView are naming containers. An update="msgs" written inside one of them looks for msgs inside it and, on both implementations in the Development project stage, failed the whole page with an error page:

The fix is an absolute id from the view root, update=":f:msgs", which is what the examples below do. The rules are the ones of the search expressions page; PrimeFaces components resolve them strictly, so a wrong id is an error on the first render, not a silently ignored update.

Ajax actions need a form. A p:poll or a menu item with an action sends its request with a form’s fields and the view state. With no h:form in the page at all, the requests of a poll and of a p:menuitem were posted every second without jakarta.faces.ViewState, the listener never ran, and the server logged nothing. When another form existed elsewhere in the page, PrimeFaces used it (the request carried that form’s name) and the listener ran. Rely on neither: put actions in a form, and keep a page with menus and polls to one form or to forms that each own their actions.

p:panel is the basic grouping box: an optional header and footer, a content area, and three built-in header features, toggling (collapse), closing and an options menu. All three are switched on by attributes and facets:

Two Ajax events exist, toggle and close, handled with p:ajax. The listener of toggle receives a org.primefaces.event.ToggleEvent (getVisibility() is Visibility.VISIBLE or HIDDEN), the listener of close a org.primefaces.event.CloseEvent.

Source: PrimeFaces 16 documentation: Panel

What the headless run showed, identical on Mojarra and MyFaces:

Other grouping containers exist in the 16.0.0 library and are used the same way (their names are tags of the library; they were not exercised for this page): p:fieldset (a bordered group with a legend, optionally toggleable), p:card, p:scrollPanel, p:overlayPanel (a pop-up anchored to a component), p:sidebar, p:splitter, p:panelGrid, p:outputPanel and p:inplace.

p:accordionPanel stacks p:tab children vertically; one tab is open at a time unless multiple="true". p:tab is the same child component as in the tab view: title (or a title facet), disabled, closable and key (a unique key that the accordion’s active accepts instead of an index since 16, see What Changed per Version). The attributes you will actually use:

The Ajax events are tabChange (a TabChangeEvent) and tabClose (a TabCloseEvent); both carry getTab(), the Tab component.

Source: PrimeFaces 16 documentation: AccordionPanel

Observed, on both implementations: clicking the second header sent one request (jakarta.faces.behavior.event=tabChange with a posted ..._tabindex field of 1), the listener ran in Invoke Application and the second header became the active one. To test the veto, isTabActionAllowed was changed to return false: the tab stayed closed in the browser, but the tabChange listener still ran, before the controller (LISTENER then CONTROLLER TabChangeEvent in the log). A listener that changes anything must therefore check the same rule itself; the controller only decides what the client is allowed to show. (The PrimeFaces documentation shows the controller as void; the method returns a boolean.) Three more points from the documentation, all consistent with the run:

p:tabView is the horizontal sibling: tab headers in a row, one panel visible. It shares p:tab, value/var, dynamic/cache, tabindex, multiViewState and the callbacks with the accordion, and adds:

A p:tab with closable="true" shows a close icon and fires tabClose.

Source: PrimeFaces 16 documentation: TabView

Observed on both implementations: with dynamic="true" the content of the second tab was not in the initial page; clicking the header sent a tabChange request with f:tabs_contentLoad=true and the tab view appeared in the render list (jakarta.faces.partial.render=f:msgs f:tabs), after which the text was there. Going back to the first tab and to the second again sent two more tabChange events without contentLoad, because the contents are cached (cache defaults to true). The listener saw activeTab=1 in the bean, so activeIndex is written to the bound property before the listener runs. Clicking the close icon of Covers removed the header and fired tabClose (Closed tab: Covers); like a closed panel, the tab is back when the page is requested again, so keep the decision on the server (a rendered condition on a bean flag) when it matters. A dynamic tab is a good place for something expensive, and the tab view is the right fit for a book page with Details, Reviews and Covers. An expensive tab belongs to a view-scoped bean; the view scope explains how much a view keeps.

p:toolbar is a bar for commands: two placeholders, left and right, defined either with facets of those names or with p:toolbarGroup children (align="left" is the default, or right). Any content may go in a group.

Source: PrimeFaces 16 documentation: Toolbar

The groups were rendered as ui-toolbar-group-left and ui-toolbar-group-right and the text read New book | Refresh | Export. The PrimeFaces documentation sample still shows p:commandButton type="push" and an image attribute from the ThemeRoller era; the current attribute for an icon is icon (a PrimeIcons class such as pi pi-plus; p:button with outcome is the navigation counterpart). Since 15 a toolbar without any rendered child is not rendered at all, and separators do not count as children. p:menuButton and p:splitButton are the compact ways to put several actions into one button.

All PrimeFaces menus are built from the same pieces. p:menuitem is one entry, p:submenu groups entries (and, in a menubar, nests), p:divider separates them. The menu components differ in how they present and where they sit.

p:dialog is an overlay window that is not visible until you show it. The two ways to show it are the client API and a server-side script; the examples use the first:

The Ajax events are close (a CloseEvent), open, move, minimize, maximize, restoreMinimize, restoreMaximize, loadContent, resizeStart and resizeStop. The standard use is an edit form:

Source: PrimeFaces 16 documentation: Dialog

How it fits together, as run:

The dialog was a child of the body (parentElement.tagName == BODY) because of appendTo="@(body)". That is deliberate and has a consequence: the dialog’s content is no longer inside the form that declared it in the page source, so give it its own h:form, as above. The PrimeFaces documentation names two reasons for appendTo: nested dialogs and a dialog inside a clipping container (a tab view, an accordion). It also says not to place a dialog in a table cell or in a positioned or overflow: hidden container. dynamic="true" was run on a separate small page: the dialog’s text was absent from the initial HTML; PF(...).show() sent a loadContent request (..._contentLoad=true), after which the text was present, and the loadContent listener ran.

PrimeFaces 16 changed the markup of the dialog (the outer ui-dialog is now the scrollable layer and a new ui-dialog-box is the box); custom CSS that targets the old structure needs to be checked, and for a dialog with long content set either modal="true" with blockScroll="true", or positionType="absolute", or use fitViewport="true" (migration guide).

A confirmation replaces the browser’s window.confirm with a styled dialog (p:confirmDialog) or a small overlay anchored to the button (p:confirmPopup). Each has two modes.

Local mode: a p:confirmDialog with a widgetVar, header, message (or a message facet) and severity (alert, the default, or info), whose buttons you write, shown by PF('deleteAllDialog').show(). It is a dialog with a message, and the p:dialog advice applies.

Global mode: one p:confirmDialog global="true" (or p:confirmPopup global="true") per page, and a p:confirm child behaviour in each button that needs it. The behaviour holds the header, message, icon and, for the popup, type="popup"; its attributes yesButtonLabel, noButtonLabel and the icon and class variants (yesButtonIcon, noButtonClass) override the dialog’s buttons; disabled switches it off and escape (default true) controls HTML escaping of the message. The buttons that answer the question carry style classes: ui-confirmdialog-yes and ui-confirmdialog-no for the dialog, ui-confirm-popup-yes and ui-confirm-popup-no for the popup. p:confirm can be put in a p:commandButton, p:commandLink or p:menuitem.

Source: PrimeFaces 16 documentation: ConfirmDialog and PrimeFaces 16 documentation: ConfirmPopup

Observed on both implementations:

The pattern is client-side confirmation: the question is asked in the browser, and an attacker, a script or a test can send the request that the buttons would send. Treat the dialog as a courtesy, and authorize and validate the action on the server as in Security Notes for This Family; the client behaviours page shows the same point for a plain onclick confirmation. p:confirm is a behavior (org.primefaces.behavior.confirm.ConfirmBehavior), which is why it is a child of the component it decorates.

The dialogs above are declared in the page. The dialog framework is the programmatic alternative: the server decides at run time to open a view in a dialog. The page of the dialog is an ordinary Faces view that is loaded into an iframe inside a dialog that PrimeFaces creates; the dialog is destroyed when the view closes it. It is the right tool for a reusable picker or editor that has its own page, its own bean and its own validation. The entry point is PrimeFaces.current().dialog() (since 7 the replacement of the RequestContext of older code; see What Changed per Version), whose methods in 16.0.0 are:

The PrimeFaces 16 documentation calls the last method showMessageInDialog; the 16.0.0 jar has showMessageDynamic and no showMessageInDialog (verified with javap). The documentation sample is out of date; use showMessageDynamic.

p:blockUI puts a translucent mask (optionally with content, such as a loading message) over a target while an Ajax request is running. block is a search expression for the target(s), trigger the id(s) of the component(s) whose requests show it (comma separated); with that wiring the mask appears at the start of the trigger’s Ajax request and disappears when it completes. blocked="true" blocks from the start, delay waits before showing, animate can be turned off, and the widget has show(), hide() and isBlocking().

Source: PrimeFaces 16 documentation: BlockUI

The mask was displayed 400 ms after the click with the text Working, please wait…​ while the action slept for 1.2 s, and was display: none afterwards, with the growl Re-index finished. Two limits from the documentation: it does not support absolutely or fixed positioned targets (a dialog, for example), and it is a visual aid only. A blocked page can still be posted to from script or another tab, so a mask is not protection against a double submit; guard the action itself (a token or an idempotent operation, as in the Post-Redirect-Get page). A page-wide busy indicator is the job of p:ajaxStatus.

p:poll sends an Ajax request at an interval from the page, runs the listener (a method expression) and updates the components named in update. The interval is in seconds by default (interval="2"; intervalType="millisecond" changes the unit). autoStart="false" waits for PF('importPoll').start(); stop="#{...}" ends polling when the expression becomes true; stop() is the client call. onactivated and ondeactivated are client callbacks that may veto, async stops the requests from queueing, global decides whether p:ajaxStatus reacts, and process, partialSubmit, form behave as on any PrimeFaces Ajax source.

Source: PrimeFaces 16 documentation: Poll

Observed on both implementations: one request per second (execute=@all, render=f:status), the text going Checks: 1, Checks: 2, Checks: 3, finished: true, and exactly three requests in total: once the listener set done, the stop expression was true in the response and the client stopped (the poll is not in the update list; the stop worked anyway). The listener ran in Invoke Application.

Polling has costs and limits. Every poll is a full Faces request with a lifecycle and, with server-side state saving, a view state lookup; a view-scoped bean stays in use, and the requests count as session activity (not measured here). Use a long interval, stop as soon as the condition is met, keep the listener to a cheap read, and prefer server push for events that should reach the page the moment they happen: the f:websocket of the push page, which replaced the removed p:push. A p:poll is the right tool when the state is only visible by asking.

Security is part of correctness for these components, because most of them take strings from data and show them in other people’s browsers.

Escape what you show. Titles and labels are escaped by default (see cross-site scripting and the escape attribute). A hostile string <img src=x onerror=...>T was put in p:panel header, p:tab title (tab view and accordion), a p:submenu label, a p:menuitem value, a breadcrumb item, a steps item, the p:dialog header, the p:confirm header and message, a growl message and the text inside a p:blockUI; on Mojarra none of them created an img element. The one place where it did was p:menuitem escape="false", which ran the script (the counter of the handler was 1). escape="false" on a label that contains user data is an XSS bug; if markup is needed, build it from your own fixed strings or sanitise it. p:confirm has an escape attribute too (default true) with the same rule.

A hidden or disabled menu is not an authorization. rendered="false" and disabled="true" on items only change what a browser is told. The action method, the outcome target and the dialog view must each check the user’s role or the ownership of the data, for example with the role checks of the security page or an @RolesAllowed-style check in the service, and the menu model of Menus from a MenuModel may hide what the user cannot use for convenience only. The same holds for p:steps: a step is not reached because the step is clickable.

A client confirmation is not a protection. See p:confirmDialog, p:confirmPopup and p:confirm.

A dialog view is a URL. See A Launcher and a Dialog View. It is also a view in its own right for CSRF: its Ajax posts carry their own view state, and the protected-view rules of the CSRF section apply to it.

Do not trust the state the client posts. The details_collapsed and details_visible hidden fields, the active tab, the selected rows: all come from the browser. Use them for presentation, not for decisions. The edit dialog of this page therefore reads the book from the service by id on the server and the save action writes only the fields of the form, never a client-supplied identity (an editor still has to check that the user may edit book id, which this scratch application does not model).

Content Security Policy. With primefaces.CSP set to true (see the CSP section) the header was Content-Security-Policy: script-src 'self' 'nonce-...';, and the edit dialog (oncomplete and args), the confirmations, the dialog framework and the panel and tab Ajax behaviours all worked unchanged on Mojarra. Plain Faces command components are the part that does not work everywhere under this policy (see the CSP section: an h:commandButton with f:ajax did not update on Mojarra); use PrimeFaces components in such a page. Keep your own oncomplete and onclick to widget calls and args, as in the examples, and move real logic to a script file loaded with h:outputScript.

PrimeFaces components are the same code on both implementations; the Faces implementation supplies the lifecycle, state saving and Ajax runtime. Every scenario of this page (panel toggle and close, accordion and tab view events and veto, dynamic and cached tabs, the declarative and model menus, context menu, breadcrumb, steps, dialog with validation and args, global and local confirmations, blockUI, poll with stop, the dialog framework round trip) gave the same results on Mojarra 4.1.17 and MyFaces 4.1.4. The differences seen were cosmetic: generated ids (j_idt11 on Mojarra, j_id_h on MyFaces) and the string form of PhaseId (INVOKE_APPLICATION 5 against INVOKE_APPLICATION(5)). Only Mojarra was used for the hostile-string test, the Content Security Policy run, the dynamic dialog and the form-less poll described above. For the comparison of the two Faces implementations in general see Versions and Implementations.

Taken from the PrimeFaces migration guides (https://primefaces.github.io/primefaces/migrationguide/16_0_0.md and the guides of earlier versions).

Faces itself: the dialogs, menus and polls use only the Ajax runtime, which was jsf.js until Faces 3.0 and faces.js since 4.0 (see the Ajax page). This page does not depend on Faces 5.0, which is still a milestone.

The PrimeFaces books of the 2013-2015 era (PrimeFaces Cookbook, second edition, for PrimeFaces 5.1/5.2 on JSF 2.2) cover these components in their layout, menus and advanced chapters. Their Ajax and component ideas still hold; the following do not: