Match Modes
What you've seen so far in the examples section is how to construct actions that modify web page parts.
Those page parts are no more than simple HTML elements.
The default Taconite behaviour is to match those elements by their identifier. If in
your XHTML tag you specify only the contextNodeId attribute, the Taconite parser
will modify the element with the provided id, or the list of elements matching the provided comma separated list
of identifiers.
Let us now add a new, indeed simple, concept: Taconite Match Modes.
Taconite let you change the default behaviour explained above by specifying a different match mode, that is,
a different way of selecting elements to modify in your web page.
At the moment, Taconite supports the following match modes:
- Plain Match : the default one, for selecting elements by their identifier.
- Wildcard Match : for selecting elements by their identifier and the "_" wildcard.
- Selector Match : for selecting elements by using standard CSS Selectors.
Let's go and see how they work.
Plain Match Mode
As already said, the Plain Match Mode is the default one, so it's the one you used in all examples so far.
You can use it without specifying anything, as you saw in the first example:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children contextNodeID="helloWorldContainer">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
Or you can explicitly specify it:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children matchMode="plain" contextNodeID="helloWorldContainer">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
As you already read in the examples section, you can also provide a comma separated list of node identifiers
into the contextNodeId attribute: Taconite will select all elements whose identifier is in the list.
Specifying the Plain Match mode with a comma separated list of node identifiers is exactly the same as above:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children matchMode="plain" contextNodeID="helloWorldContainer1, helloWorldContainer2">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
So it's just a matter of specifying the matchMode="plain" attribute, as you can see at Line 5.
Nothing new so far ... now let's go to see the Wildcard Match!
Wildcard Match Mode
The Wildcard Match Mode is a way of selecting multiple elements through the use of a special wildcard character: the underscore ("_").
An element in your web page will match one of the node identifiers provided by the contextNodeId attribute of your action
if its identifier starts with a substring of one of the cited node identifiers and ends with the "_" wildcard.
So, the wildcard must be applied to the elements in the web page.
A short example will clarify much more than thousand words:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children matchMode="wildcard" contextNodeID="message.hello.world">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
As you can see at Line 5, it's just a matter of putting the attribute matchMode="wildcard".
Other than that, note the standard contextNodeID="message.hello.world"
The action above will match the following elements:
01 <div id="message.hello.world"/>
02 <div id="message.hello._"/>
03 <div id="message._"/>
The action above with contextNodeID equal to "message.hello.world", will match:
- The div at Line 1, because its id is the same as the action contextNodeId.
- The div at Line 2, because its id starts with a substring of the contextNodeId ("message.hello.") and ends with the "_" wildcard.
- The div at Line 3, because its id starts with a substring of the contextNodeId ("message.") and ends with the "_" wildcard.
The same applies if you provide a comma separated list of identifiers:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children matchMode="wildcard" contextNodeID="message.hello.world, message.goodbye.world">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
The action above will match the following elements:
01 <div id="message.hello.world"/>
02 <div id="message.hello._"/>
03 <div id="message.goodbye.world"/>
04 <div id="message.goodbye._"/>
The elements at Line 1 and 2 match the first identifier in the contextNodeId list, the elements at Line 3 and 4 match the second one.
Selector Match Mode
The Selector Match Mode uses standard CSS Selectors.
CSS Selectors provides a rich and powerful sintax for selecting element nodes in the DOM tree.
Taconite supports CSS1/CSS2 Selectors, plus a subset of the CSS3 Selectors syntax.
Here are, in details, all supported CSS Selectors:
| Pattern | Meaning | CSS level |
|---|---|---|
| * | any element | 2 |
| E | an element of type E | 1 |
| E[foo] | an E element with a "foo" attribute | 2 |
| E[foo="bar"] | an E element whose "foo" attribute value is exactly equal to "bar" | 2 |
| E[foo~="bar"] | an E element whose "foo" attribute value is a list of space-separated values, one of which is exactly equal to "bar" | 2 |
| E[foo^="bar"] | an E element whose "foo" attribute value begins exactly with the string "bar" | 3 |
| E[foo$="bar"] | an E element whose "foo" attribute value ends exactly with the string "bar" | 3 |
| E[foo*="bar"] | an E element whose "foo" attribute value contains the substring "bar" | 3 |
| E[attr|="value"] | an E element whose "attr" attribute has a hyphen-separated list of values beginning (from the left) with "value" | 2 |
| E:first-child | an E element, first child of its parent | 2 |
| E:last-child | an E element, last child of its parent | 3 |
| E:empty | an E element that has no children (including text nodes) | 3 |
| E#myid | an E element with ID equal to "myid". | 1 |
| E.myClass | an E element with class name equal to "myClass" (HTML only). | 1 |
| E F | an F element descendant of an E element | 1 |
| E > F | an F element child of an E element | 2 |
| E + F | an F element immediately preceded by an E element | 2 |
| E ~ F | an F element preceded by an E element | 3 |
To construct actions that select elements to modify by using CSS Selectors is easy as constructing any other action:
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children matchMode="selector" contextNodeSelector="div#my.container > div#my.child">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
Just note, at Line 5:
- The matchMode="selector" attribute, specifying the proper match mode.
- The contextNodeSelector="div#my.container > div#my.child" attribute, in place of the contextNodeID attribute, specifying a single or comma separated list of CSS selectors to use.
Summary
Taconite Match Modes are an orthogonal concept in respect to actions.
They are completely independent: you are free to construct your actions and then choose whatever match mode
you want to apply by simply tweaking some XML attribute.
That's the power of simplicity!