Core Tags (f:)

Some core tags are covered by other pages because they belong to a larger topic. This page deals with the general-purpose tags in the table’s first group and points to the right page for the rest.

Source: Jakarta EE Tutorial: Using Core Tags

Most of these tags are handled while the view is being built (the Restore View phase of every request, see the lifecycle page), a few act when an event happens later in the lifecycle, and a few are read at render time:

f:attribute stores a named value in the attribute map of the closest parent component (component.getAttributes()). Its two attributes are name and value, and both accept expressions. It is the tag for passing a small piece of information from the page to code that receives a component: an action listener, a validator, a converter or a custom renderer.

A literal value is stored as it is. An EL expression is stored on the component and evaluated each time the attribute is read, so inside an iteration each row sees its own value. The following page offers one link per book and tells the listener which book was picked without any request parameter:

Posting the second link (shelf:rows:1:pick) produced Last: 9780547928227, the ISBN of the second book, on both implementations. In a real application prefer an EL method call with a parameter (action="#{attributeBean.open(book)}", shown under action listeners), which is typed and needs no cast. f:attribute remains the right tool when the receiver is generic code that only has the component, such as the validator below.

Source: Jakarta Faces 4.1 VDL: f:attribute

A validator that must know a limit chosen in the page reads it from the component it is validating:

Submitting 1850 with a floor of 1900 displayed Year must be at least 1900. The validator page covers @FacesValidator, validator methods and default validators in depth. One related detail seen in the scratch run: with the CDI mode annotated (the beans.xml of the Bookshelf), a validator declared as @FacesValidator(managed = true) was not found until it also carried a bean-defining annotation such as @Dependent; the error read "could not be resolved by CDI".

Source: Jakarta Faces 4.1 VDL: f:attribute

f:param adds a child UIParameter component (component type jakarta.faces.Parameter) to the closest parent component. The attributes are name, value, id, binding and disable; disable takes a boolean and leaves the parameter out when true. What the parameter means depends on the parent, because the parent’s renderer decides what to do with its UIParameter children:

The VDL documentation lists the Output, Link and OutcomeTarget Link renderers as the ones that consult the UIParameter children. The scratch run also showed h:commandButton carrying the parameter in its generated submit script on both implementations (a post with the parameter reached the bean on Mojarra), but that is implementation behaviour rather than a documented guarantee, so use a link or an EL method call when the value matters.

The output of the first request was Dune by Frank Herbert (1965), and the link of the first book was book.xhtml?isbn=9780441013593&tab=reviews; for a book older than 1950 the tab pair disappeared because of disable. MyFaces writes the query pairs in a different order (tab before isbn for the third book), so never depend on the order. Posting the borrow link with isbn=9780547928227 printed borrow requested for 9780547928227. jakarta.faces.annotation.ManagedProperty injects the request parameter into a CDI bean property (@Inject is required with it).

Two details about h:outputFormat showed up in the run:

Source: Jakarta Faces 4.1 VDL: f:param and Jakarta Faces 4.1 VDL: h:outputFormat

A facet is a named child component with a special role in its parent. Unlike ordinary children it is not part of the child list: the parent finds it by name (component.getFacet("header")) and decides where to render it. f:facet takes one required attribute, name. The standard HTML components use these facets:

The caption facet is rendered inside a caption element below the table element, header and footer become thead and tfoot rows, and colgroups (data table only) holds one component that renders colgroup and col elements.

The rendered HTML (whitespace trimmed) was:

Notice the table-level header: the two h:outputText children of one f:facet rendered one after the other (All books (3)). The VDL says that when a facet has more than one child the implementation puts them in a container UIPanel automatically. The h:dataTable documentation still describes its colgroups facet as accepting one child, so wrap several elements yourself with a h:panelGroup when a renderer expects a single component. The data table page goes deeper into tables.

Facets also appear in composite components (cc:facet, cc:renderFacet, cc:insertFacet) and in custom components, where the component class reads them with getFacet(name) and the renderer calls encodeAll on them. Those uses are explained on the composite components and custom components pages.

Source: Jakarta Faces 4.1 VDL: f:facet and Jakarta Faces 4.1 VDL: h:dataTable

The select components (h:selectOneMenu, h:selectManyCheckbox, h:selectOneRadio and the rest, see the page on HTML components) get their options from these three tags nested inside them.

The escaping flag is named differently on the two tags: itemEscaped on f:selectItem and itemLabelEscaped on f:selectItems. In the scratch run, a label <b>two</b> with itemEscaped="false" on f:selectItem rendered as real bold markup, while itemLabelEscaped="false" on a single f:selectItem was ignored and the markup stayed escaped. Both implementations behaved alike. Leave escaping on (the default) for every label that includes user data.

What the run showed:

Where it sits in the lifecycle: the option list is evaluated when the menu is rendered, and again in Process Validations, where Faces checks that the submitted value is one of the options. A list that changes between the render request and the postback, because it depends on a request-scoped property or on other fields, makes valid submissions fail with "Value is not valid". Keep the list stable for the life of the view, for example by loading it once in a @ViewScoped bean or in a @PostConstruct method.

Source: Jakarta Faces 4.1 VDL: f:selectItem, f:selectItems and f:selectItemGroups

f:view is the root tag of a Facelets page. It is optional, because a UIViewRoot exists whether or not the tag is written, but it is the only place to set properties of the view in markup. All its attributes accept expressions:

f:view also holds f:metadata, which must be its direct child (see the next section). The tag appears in templates because the template is the file that owns the html element; the page that names the template contributes the content.

Requesting detail.xhtml?isbn=9780441013593 returned Welcome to the Bookshelf, Dune; adding &lang=es returned Bienvenido a la Bookshelf, Dune and a Spanish title, on both implementations. The locale expression is read when the view is rendered, after the view parameters were applied, which is why a view parameter can drive it. The response header was Content-Type: text/html;charset=UTF-8. A request without isbn fails the required check and, in the Development project stage, shows the message at the foot of the page.

beforePhase and afterPhase give one view its own phase hooks without a global PhaseListener:

On a postback the trace read after RESTORE_VIEW | before APPLY_REQUEST_VALUES | after APPLY_REQUEST_VALUES | before PROCESS_VALIDATIONS | after PROCESS_VALIDATIONS | before UPDATE_MODEL_VALUES | after UPDATE_MODEL_VALUES | before INVOKE_APPLICATION | after INVOKE_APPLICATION | before RENDER_RESPONSE: there is no before RESTORE_VIEW entry, exactly as the VDL describes. The first request of the page showed only after RESTORE_VIEW and before RENDER_RESPONSE. (TraceBean is a static helper that collects the strings. The trace is printed while the page is rendered, so an after RENDER_RESPONSE entry can only show up in the page of the next request.)

transient="true" makes a stateless view: the hidden jakarta.faces.ViewState field was rendered with the value stateless on both implementations, and no server-side view state is kept. The VDL warns that transient views cannot be used with @ViewScoped beans. The page on state saving explains the trade-offs.

Source: Jakarta Faces 4.1 VDL: f:view and f:view and f:metadata in the Facelets overview

f:metadata declares the view metadata: the things that describe how a view is entered and that must be processed before the whole component tree is built. It holds f:viewParam (read and convert request parameters), f:viewAction (run a method on the initial request) and f:event (system events). The specification describes how, with view metadata, the Restore View phase can create a metadata-only view first; it is also what lets h:link and h:button build bookmarkable URLs for a target view (specification section 2.5.6, Bookmarkability).

The VDL fixes the placement rules:

To keep f:view in a template while each page declares its own metadata, the template exposes a slot for it:

Requesting tpl-good.xhtml?isbn=9780441013593 printed isbn=9780441013593 title=Dune on Mojarra and MyFaces. Moving the same f:metadata block into the template itself (bad.xhtml in the run) printed isbn= title= on both: the parameter was never read and no error or warning was raised. If a view parameter seems to be ignored, check that the metadata is not in a template. The page on view parameters and view actions explains the parameters themselves in depth. See the templating page for ui:insert and ui:define.

Source: Jakarta Faces 4.1 VDL: f:metadata and Jakarta Faces 4.1 specification, 2.5.6 Bookmarkability

f:event installs a ComponentSystemEventListener on the closest parent component for one system event. Attributes:

Any class that extends ComponentSystemEvent can be named in type by its fully qualified name. If the class is annotated with @NamedEvent, its shortName is usable as the type.

The log printed on the page, with the preRenderView listener from the metadata above, was:

so the events arrive in this order: component added (build), view about to render, component about to render. Mojarra and MyFaces gave the same order.

preRenderView is the traditional hook for loading data once the view parameters are applied, but it fires on every request that renders the view, postbacks included, which is why the example prints isPostback(). f:viewAction is usually better for initial-request logic because it can navigate and can be limited to the initial request; see its page.

postValidate on a container is the standard way to do validation that involves several fields. The listener runs after the container’s children were validated and so can read their values and mark the view as failed:

Posting from=10 and to=5 re-displayed the form with Return day must not be before the start day and did not call submit(); from=5, to=10 called it. The check on isValid() matters: a failed conversion or required check leaves the local value unset. The page on validators compares this with f:validateWholeBean and Bean Validation (Bean Validation page).

A custom event is a class that extends ComponentSystemEvent and carries @NamedEvent:

Both the short name and the class name reached the listener (bookAdded heard by shelf twice) on both implementations.

Source: Jakarta Faces 4.1 VDL: f:event and API: NamedEvent

f:loadBundle loads a ResourceBundle and exposes it as a java.util.Map in the request scope. Attributes: basename (the bundle base name) and var (required, the name of the request attribute). The bundle is looked up for the locale of the current view, so f:view locale controls it. This is the page-local way to reach messages; the application-wide alternative is <resource-bundle> in faces-config.xml, which the page on messages and internationalisation covers.

The output was [Catalogue] [Welcome to the Bookshelf, {0}], Welcome to the Bookshelf, Alberto and Title, identical on both implementations. Things the run confirmed:

Source: Jakarta Faces 4.1 VDL: f:loadBundle

f:subview is a naming container tag: it creates a UINamingContainer that prefixes the client ids of everything inside it. Attributes: id (required), rendered and binding. The VDL says it is useful when a section that is included with ui:include (or any tag that includes another page dynamically) appears more than once in a view and its component ids would collide.

Including the same file twice inside one form fails, because the component ids inside the file are not unique:

The first page failed on Mojarra with IllegalStateException: Component ID f:query has already been found in the view and on MyFaces with DuplicateIdException: Component with duplicate id "f:query" found. The second rendered two inputs with the ids f:left:query and f:right:query. The same file bound to the same property twice is only a demonstration of the id rule; give each section its own value expression, for example through ui:param, in a real page.

Where f:subview was once the standard tool to keep JSP includes apart, Facelets has better ones: a composite component is already a naming container, and ui:repeat and h:dataTable each create one per row. Use f:subview for the cases that remain. The JSF 2.0 change log of the specification lists a request (issue 852) to mark f:subview and f:verbatim as deprecated in the VDL documentation; the 4.1 VDL page of f:subview carries no deprecation note.

Source: Jakarta Faces 4.1 VDL: f:subview

In JSF 1.x views written as JSP pages, template text and HTML around Faces tags was written to the response before the component tree existed, so it appeared out of order. f:verbatim wrapped such text in a component so that it stayed in place. Facelets builds the tree from the XML and never has the problem, and JSP views were removed in Faces 4.0.

f:verbatim has no page in the 4.1 VDL documentation. A page that used it:

failed to build on both implementations: Mojarra reported Tag Library supports namespace: jakarta.faces.core, but no tag was defined for name: verbatim and MyFaces printed the same sentence. Delete the tag and write the markup directly. If text must be escaped, use h:outputText; if it must not be escaped (trusted content only), use h:outputText with escape="false", which carries the same cross-site-scripting risk as before.

Source: Jakarta Faces 4.1 VDL: f: tag library summary (it has no f:verbatim entry)

When a form fails validation, each input keeps the submitted value, so a "Cancel" button that merely re-renders the page shows the invalid text again. UIViewRoot.resetValues(FacesContext, Collection<String>) clears the submitted and local values of the components with the given client ids so that they show the model values again. f:resetValues is the tag that calls it from an action. It has one attribute, render, a space-separated list of client ids, and it registers an action listener on the closest ActionSource.

Both implementations register the tag (ResetValuesHandler in Mojarra, ResetValuesActionListenerHandler in MyFaces), but it has no entry in the 4.1 VDL documentation, so treat it as a convenience provided by both implementations rather than a portable tag. f:ajax has a documented equivalent, the resetValues attribute, whose render list is likewise "a space separated list of client identifiers suitable for passing directly to UIViewRoot.resetValues()`" (VDL); the Ajax page covers it. Faces 5.0 is planned to add a `clearModel attribute to f:resetValues (issue 1940 on the specification project, listed on the 5.0 specification page): the issue describes it as the counterpart of PrimeFaces' clearModel flag, which does not only reset the component state but also sets the model value to null. It does not exist in 4.1 and nothing here relies on it; the planned list is on the versions page.

With an empty reviewer and abc in rating posted:

The ids must be the full client ids: render="f:fields" worked, while render="fields" and render="@form" changed nothing, on both implementations. The button is immediate="true" so that it runs in Apply Request Values and skips validation (the lifecycle consequences of immediate are on the lifecycle page).

Source: API: UIViewRoot.resetValues and, for the planned clearModel, Jakarta Faces 5.0 (under development) with issue 1940

A command component (h:commandButton, h:commandLink) can run three kinds of code when it is activated:

f:actionListener registers an ActionListener implementation, either by class with type (a fully qualified name) or by instance with binding (an expression that evaluates to a listener). for targets a nested attached object inside a composite component. f:setPropertyActionListener copies a value into a property when the command fires: value is the source expression (required) and target is the destination expression (required); the value is coerced to the type of the target. Both are ActionSource listeners: they work on h:commandButton and h:commandLink and not on h:link/h:button, which are navigation components.

Posting the second open button gave, identically on Mojarra and MyFaces:

So the order is: the actionListener attribute first, then the registered listeners in the order of the tags (the property setters fill selected and selectedIsbn here), then action, which therefore already sees the selected values. Two points to keep in mind:

Posting open2 (the EL method call) printed openBook(The Fellowship of the Ring) on both. The EL form action="#{listenerBean.openBook(book)}" is typed, needs no extra tag, and has been available since EL 2.2 method parameters in the Facelets expression language (the page on the Expression Language covers it); prefer it to f:setPropertyActionListener in new code. f:setPropertyActionListener still has its place when the target must be set before another listener runs, or when the code is written for an EL implementation without method parameters.

A listener has one more limit worth knowing: with immediate="true" on the command, its listeners run in Apply Request Values, before conversion and validation of the other inputs, so the properties they set can hold values that were never validated. See the lifecycle page and the page on events and listeners for AbortProcessingException and ActionEvent details.

Source: Jakarta Faces 4.1 VDL: f:actionListener and f:setPropertyActionListener