Reimplement th:include/th:substituteby/th:replace syntax with new DOM Selector syntax

[danielfernandez]

Currently, as of 2.0.x, the th:include (or th:substituteby, or th:replace) syntax makes a difference between:

<div th:include="mytemplate :: myfragment">...</div>

...which means look for a tag in the mytemplate template that is marked as th:fragment="myfragment" and:

<div th:include="mytemplate :: [//div[@id='myfragment']]">...</div>

...which means look for a <div>tag in the mytemplate template that is marked as id="myfragment".

There is, therefore, a difference in syntax between the first type of fragment selection, which is based on th:fragment and the second one, which has to be specified between brackets ([...]) and is based on the execution of a DOM Selector.

Applying the new syntax

In order to achieve the more integrated syntax that will be later needed to implement #180, we need to be able to specify DOM Selector -based fragment selections without the surrounding brackets, as:

<div th:include="mytemplate :: //div[@id='myfragment']">...</div>

...and this means we should be able to integrate the search for th:fragment="myfragment" into the DOM Selector syntax, so that everything (both tag selection based on paths/attributes and also the search for th:fragment) is a DOM Selector.

How can this be done? By means of the new capabilities of DOM Selectors implemented in #202. Specifically, by considering th:fragment attributes as a node reference, and implementing its search as an implementation of the DOMSelector.INodeReferenceChecker interface.

Thanks to that, the following syntaxes should be equivalent:

<div th:include="mytemplate :: myfragment">...</div>
<div th:include="mytemplate :: %myfragment">...</div>

..and we should be able to express the id-attribute based selection we saw above also in several equivalent ways:

<div th:include="mytemplate :: //div[@id='myfragment']">...</div>
<div th:include="mytemplate :: div[@id='myfragment']">...</div>
<div th:include="mytemplate :: div#myfragment">...</div>
<div th:include="mytemplate :: #myfragment">...</div>

Refer to #202 for more information on all the possibilities of this DOM Selector syntax.

Finally, note this th:fragment node reference mechanism should be able to identify fragment names even if they contain parameters, so that:

<div th:fragment="myfragment (oneparam, twoparam)">...</div>

Should be correctly referenceable as %myfragment.