Search Expressionssince 0.8.0

Inspired by PrimeFaces, BootsFaces implements a couple of powerful search expressions to make your life easier. In almost every case, you can get rid of ids. Use @form, @next,@previous,@parent and even jQuery-Expressions like @(.css-class) instead.

State of the art

The search expressions can be used with the update and process attributes of the AJAX-enabled BootsFaces components. For these components, the search expressions should also work with traditional <f:ajax /> facets (although we discourage the use of these AJAX facets - in most cases you don't need them).

Basic usage

Like in standard JSF, you can use ids to determine which region of the DOM to update:

The preceding colon indicates that :tabViewId isn't inside the "naming container" - usually a form or a custom composite component - but in the root of the JSF component tree. The panelId is direct descendant of the form, so it doesn't need a colon.

Standard JSF search expressions

Standard JSF introduces several search expressions, basically shortcut allowing you to get rid of the ids in many cases:

• @form is the form surrounding the button.
• @this the the command button itself.
• @all is the entire JSF page. Note that BootsFaces doesn't support @all yet. In any case, use @all only in there's no other way: it's very inefficient, because it forces every JavaScript library to reinitialize.
• @none is an exotic special case. It doesn't update anything. You sometimes need it to trigger an action on the server, but don't want to display anything new on the client.

PrimeFaces search expressions supported by BootsFaces

PrimeFaces adds a couple of very useful search expressions, which are supported by BootsFaces, too. (Actually, @next and @previous originally were contributed to PrimeFaces by one of the BootsFaces team members):

• @previous finds the previous JSF element in the same level of the JSF tree. Note that this usually is different from the predecessor in the HMTL tree.
• @next finds the next JSF element in the same level of the JSF tree.
• @parent finds the parent element of the current widget in the JSF tree.
• @child(n) yields a certain child of the currently selected JSF subtree. However, I don't recommend using this search expression. It's extremely vulnerable to changes of your JSF view.
• @() jquery expressions. These expressions are evaluated on the client. The most useful application is @(.css-class) to find one or more elements with a given CSS class. The advantage of the jQuery expressions is that you aren't restricted to by the JSF tree. Instead, the jQuery expressions always searches the entires DOM tree. Be careful: sometimes this can result in unexpected results, such as sending multiple forms simultaneously to the server, which is forbidden by HTML. Note that the algorithm parsing the jQuery expression is very primitive. Don't add spaces to the jQuery expression. Otherwise, it is treated as two distinct jQuery expressions. Note that this search expression can only be used for the update and process. Every other attribute requires a search expression evaluated on the server-side, such as @styleClass.
• @root is the root of the JSF tree. It's equivalent to the preceding colon.

BootsFaces search expressions

BootsFaces introduces several search expressions, basically shortcuts allowing you to get rid of the ids in many cases. Note that most BootsFaces search expression scan the entire JSF tree recursively, which may result in a performance penalty. If that's an issue, you can optimize the performance by limiting the search to a subtree. For instance, @property("myBean.myProperty") scans the entire JSF tree, while @form:@property("myBean.myProperty") limits the search to the current form.

• @after since 0.9.0 is similar to @next, but it yields every JSF node following the current one. Very useful if one of more input fields are to be activated or deactivated depending on a checkbox. There's an example below.
• @before since 0.9.0 is similar to @previous, but it yields every JSF node preceding the current one.
• @findIdRecursive(id) find an id anywhere in the JSF tree below the currently select node. For instance, @form:**:someId looks for someId, considering the entire form. breaking change in 1.0.2 Since 1.0.2, this may result multiple ids. Until 1.0.1, this search expression only returned the first id in the JSF tree (if any).
• ** shortcut for @findIdRecursive
• @id and @findIdRecursively are synonyms of @findIdRecursive
• @findId(id) find an id, but restrict the search to the top-most level of the tree
• *:id shortcut for @findId
• @findPartialId(id) find one or many ids, given by a wildcard expression: *suffix, prefix* or prefix*suffix. Only the topmost level is considered.
• *id shortcut for @findPartialId
• @findPartialIdRecursive(id) find one or many ids, given by a wildcard expression: *suffix, prefix* or prefix*suffix. Searches the entire tree.
• **:*id or **:id* or **:*id* shortcut for @findPartialIdRecursive
• @property(EL_Expression) since 1.0.0 finds a JSF component by its EL expression. You can omit the curly braces and the "#". In other word, @property takes the fully qualified variable name as parameter. This search expression can return multiple ids if there's more than one input field with the same EL expression (e.g. on different tabs).
• @styleClass(class) since 1.0.0 is a server-side variant of @(.class). It returns a list of the UI components bearing a certain CSS style class. Note that this search expression scans the entire JSF tree.

PrimeFaces search expressions BootsFaces does not support

There are a few PrimeFaces search expressions BootsFaces does not support:

• @namingcontainer
• @composite
• @row(n)
• @widgetVar(name) (doesn't make sense in BootsFaces, because BootsFaces doesn't use the concept of client-side widgets)

Classical use cases

The reason why one of us (Stephan) originally invented @next and @previous was that he'd observed that input fields typically occur as a triplet: a label, the input field itself and an error message. It's rather cumbersome and error-prone to implement this using ids, but it's pretty straightforward with @next and @previous. As a bonus, you can copy and paste input field much more easily, and you can even move them from one form to another without updating the id. In fact, the only reason why the example below uses ids is because you need to knwo the id in order to create messages on the server side.

@after comes in handy if you've got a complex form. Let's add a switch to the previous example. The input field is hidden until the switch is activated. Of course, both the label and the error message have to be hidden, too. You can achieve this with update="@after":

However, this example also shows that the validation logic of JSF usually gets in your way when you try to hide or show fields depending on other fields. Better use JavaScript instead.

More advanced live demo

This demo shows some of the options at a glance.

All-in-One-Demo (aka cheat sheet)

This demo shows most options on a single screen. Most buttons modify the images. The buttons in the image row modify the image in the same row. The buttons below modify the entire page. Some buttons also show the appearance of the button itself (by counting up the numbers). As you can see, you can freely combine every option the search expression framework gives you.