Templating¶
EXT:solr uses an advanced version of the marker templating system. The reason for this is a pure historical one. When we started working on the extension in early 2009 TYPO3 4.2 still was the current version and TYPO3 4.3 was still in development, extbase and fluid were not stable enough yet - basically changing every day - and we had to support TYPO3 installation down to 4.0. We also did not have to completely invent the template engine as it was taken from the code base of EXT:community back then.
It is planned to move to fluid in a later version, if you want to help, please let us know!
The template engine offers features and a syntax similar to fluid. This includes if conditions, loops, and view helpers. It uses the known triple hash, i.e., ### markers though.
In the following sections we explain the several features of the templating system.
Markers¶
Markers represent either associative arrays or objects and their properties (exposed by getter methods). The notation is object name followed by a dot followed by the property name or key in case of an array. The property part is pretty flexible in accepting different ways of upper/lower case naming.
These are equal:
###RESULT_DOCUMENT.title### (recommended) ###RESULT_DOCUMENT.TITLE###
These variants of dynamic fields are equal, too:
###RESULT_DOCUMENT.customField_stringS### (recommended) ###RESULT_DOCUMENT.CUSTOM_FIELD_STRING_S### ###RESULT_DOCUMENT.customFieldStringS###
For dynamic fields we recommend you simply use the same casing as in the index
Subparts¶
Subparts of a template have a name and are limited by a beginning and an end marker. E.g. the subpart SOLR_SEARCH_FORM is defined like this:
1 <!-- ###SOLR_SEARCH_FORM### begin -->
2 /* Some HTML markup */
3 <!-- ###SOLR_SEARCH_FORM### end -->
Technically the extension is structured using the command pattern and each command has its own subpart.
Conditions¶
EXT:solr provides the classic if conditions that you are used to in PHP. They consist of two comparands, an operator and a subpart that gets rendered if the condition is fulfilled.
The following operators are supported:
- ==
- !=
- <
- <=
- >
- >=
- %
E.g. if you want to render a given HTML markup only if the result document's type is "pages" you can use the == operator:
1 <!-- ###IF:###RESULT_DOCUMENT.TYPE###|==|pages### begin -->
2 <strong>It's a page!</strong>
3 <!-- ###IF:###RESULT_DOCUMENT.TYPE###|==|pages### end -->
Currently "else" is not supported.
Note:
There is one limitation when using IF statements. Due to the regular expressions used to parse the templates for the IF markers you cannot use two if blocks with the same markers, even if they wrap different content.
Example:
1 ###IF:###RESULTS.FOUND###|>|0###
2 <div style="border: 1px solid red; padding: 10px;">foo</div>
3 ###IF:###RESULTS.FOUND###|>|0###
4
5 ###IF:###RESULTS.FOUND###|>|0###
6 <div style="border: 1px solid green; padding: 10px;">bar</div>
7 ###IF:###RESULTS.FOUND###|>|0###
The result will be, that for both cases the output is the content of the first IF subpart.
We currently do not plan to fix this issue since the regular expression is quite complex and it is planned to move to fluid anyway.
However, you can easily work around this issue by simply making sure that each IF block is different in its parameters and can thus be distinguished by the template engine. You can achieve this by simply adding a fourth parameter to the IF markers which will have no effect on the output.
Example:
1 ###IF:###RESULTS.FOUND###|>|0|foo###
2 <div style="border: 1px solid red; padding: 10px;">foo</div>
3 ###IF:###RESULTS.FOUND###|>|0|foo###
4
5 ###IF:###RESULTS.FOUND###|>|0|bar###
6 <div style="border: 1px solid green; padding: 10px;">bar</div>
7 ###IF:###RESULTS.FOUND###|>|0|bar###
Loops¶
Loops are used to access each element of a collection.
For example, the default results template provided that comes with the extension uses a loop to render all result documents (we've simplified the code a little bit):
1 <!-- ###LOOP:RESULT_DOCUMENTS### begin -->
2 <!-- ###LOOP_CONTENT### -->
3
4 <h3>###RESULT_DOCUMENT.TITLE###</h3>
5 <p>###RESULT_DOCUMENT.CONTENT###</p>
6
7 <!-- ###LOOP_CONTENT### -->
8 <!-- ###LOOP:RESULT_DOCUMENTS### end -->
As you can see, the loop is specified by the keyword LOOP and gets the name of the collection as argument, RESULT_DOCUMENTS in this case.
The subpart LOOP_CONTENT marks the template which gets executed for each loop iteration. Inside this subpart a custom variable, in this case RESULT_DOCUMENT, is available for further usage.
The result documents loop¶
The result documents loop used in the example above iterates through all the results returned by Solr for the current results page. The result document object provides its fields as properties. These properties will also include the dynamic fields you may be using. See the general part about markers further up for more details.
View Helpers¶
We provide several view helpers that keep your templates clean. View helpers are basically functions that can get called in templates and return some kind of HTML markup.
They can have strings, numbers or subparts as arguments, where arguments are separated by pipe "|" character.
By default the extension comes with the following view helpers:
CROP¶
Shortens the string argument.
Usage: ###CROP:string|maxLength|cropIndicator|cropFullWords###
- string: The string to shorten
- maxLength: maximum string length, default: 30 (optional)
- cropIndicator: string appended to the shortened string, default: ... (optional)
- cropFullWords: Whether to crop after word boundaries only, default: 1 (optional)
The CROP view helper can also be configured through TypoScript under plugin.tx_solr.viewhelpers.crop. You can configure all the optional parameters with the names as listed above.
CURRENT_RESULT_NUMBER¶
Renders the number of the current result document. Can only be used in the result loop.
Usage: ###CURRENT_RESULT_NUMBER:###LOOP_CURRENT_ITERATION_COUNT######
DATE¶
Renders a Unix timestamp as date.
Usage: ###DATE:timestamp###
The date format can be configured through plugin.tx_solr.general.dateFormat and uses the PHP date function's format.
FACET¶
You can use this view helper to render a single facet independently from the facet list.
Usage: ###FACET:facetName### facet rendering subpart ###FACET:facetName###
Example:
1 <!-- ###FACET:type### begin -->
2 <!-- ###SINGLE_FACET### begin -->
3 <li class="facet facet-###FACET.name###">
4 <h5>###FACET.label###</h5>
5 <ul>
6 <!-- ###SINGLE_FACET_OPTION### begin -->
7 <!-- ###LOOP:FACET_LINKS### begin -->
8 <!-- ###LOOP_CONTENT### -->
9 <li class="###FACET_LINK.HIDDEN###">
10 ###FACET_LINK.LINK### ###FACET_LINK.COUNT###
11 </li>
12 <!-- ###LOOP_CONTENT### -->
13 <!-- ###LOOP:FACET_LINKS### end -->
14 <!-- ###SINGLE_FACET_OPTION### end -->
15 ###FACET.showAllLink###
16 </ul>
17 </li>
18 <!-- ###SINGLE_FACET### end -->
19 <!-- ###FACET:type### end -->
This would render the facet named "type". Please note that this view helper needs two markers, one begin and one end marker.
LINK¶
Use this view helper to render regular links (typolink) in your template.
Usage: ###LINK:linkText|linkTarget|additionalParameters|useCache###
- linkText: obviously the text to use for the link
- linkTarget: The page Id to link to or a URL or a path to a TypoScript object like lib.myObject which dynamically resolves a page Id
- additionalParameters: additional GET parameters for the URL (optional)
- useCache: Whether to use caching (cHash), default: 0 (optional)
LLL¶
Renders a *L*ocal *L*anguage *L*abel.
Usage: ###LLL:languageKey###
languageKey can be a a key of the Solr extension's language labels or a full path to a language file in another extension starting with EXT:.
MULTIVALUE¶
Renders an array returned from a multivalue field.
Usage: ###MULTIVALUE:array|glue###
- array: The array returned by a multivalue Solr document field
- glue: The string used to concatenate the array's values, default: ", " (optional)
Example:
###MULTIVALUE:###RESULT_DOCUMENT.multivalueField###|,###
The default glue value can also be configured through TypoScript: plugin.tx_solr.viewhelpers.multivalue.glue.
The array must be provided in serialized form. When indexing you can index the field as a regular multivalue field. To turn the mulitvalue field into a serialized array during output use plugin.tx_solr.search.results.fieldProcessingInstructions.[fieldName] = serialize. This is only necessary with version 2.0, later versions fix this by automatically detecting the multivalue field and then turning it into a serialized array.
ODD_EVEN¶
Use this view helper to create "zebra stripe" result lists.
Usage: ###ODD_EVEN:number###
Depending on the number, the view helper will return "odd" or "even".
Example:
1 <!-- ###LOOP:RESULT_DOCUMENTS### begin -->
2 <!-- ###LOOP_CONTENT### -->
3 <div class="row-###ODD_EVEN:###LOOP_CURRENT_ITERATION_COUNT######">
4 ###RESULT_DOCUMENT.TITLE###
5 </div>
6 <!-- ###LOOP_CONTENT### -->
7 <!-- ###LOOP:RESULT_DOCUMENTS### end -->
RELEVANCE¶
Renders the relevance of a result relative to the most relevant result as percent value.
Usage: ###RELEVANCE:resultDocumentScore###
- resultDocumentScore: The result document's score value for the overall result set.
Example:
Relevance: ###RELEVANCE:###RESULT_DOCUMENT.SCORE######%
Note, you have to add the percent sign yourself.
RELEVANCE_BAR¶
Renders a result document's score as a graphical representation / bar graph.
Usage: ###RELEVANCE_BAR:resultDocumentScore###
- resultDocumentScore: The result document's score value for the overall result set.
Example:
Relevance: ###RELEVANCE_BAR:###RESULT_DOCUMENT.SCORE######
SOLR_LINK¶
Similar to the LINK view helper, creates a link, but this one also keeps the extension's tx_solr GET parameters.
Usage: ###SOLR_LINK:linkText|linkTarget|additionalParameters|useCache###
- linkText: obviously the text to use for the link
- linkTarget: The page Id to link to or a path to a TypoScript object like lib.myObject which dynamically resolves a page Id, default: current page (optional)
- additionalParameters: additional GET parameters for the URL (optional)
- useCache: Whether to use caching (cHash), default: 0 (optional)
SORT_INDICATOR¶
Creates a graphical representation of the current sorting direction.
Usage: ###SORT_INDICATOR:sortDirection###
- sortDirection: "asc" for ascending of "desc" for descending
Example:
1 <ul>
2 <!-- ###LOOP:SORT### begin -->
3 <!-- ###LOOP_CONTENT### -->
4 <li>
5 ###SORT_INDICATOR:###SORT.CURRENT_DIRECTION###### ###SORT.LINK###
6 </li>
7 <!-- ###LOOP_CONTENT### -->
8 <!-- ###LOOP:SORT### end -->
9 </ul>
SORT_URL¶
Creates a solr sorting URL to use when f.e. rendering the sort options as a <select> element instead of a list.
Usage: ###SOLR_URL:sortOption###
TS¶
Renders an arbitrary TypoScript content object defined by a TypoScript path.
Usage: ###TS:path.to.some.ts.property.or.content.object###
You can also provide arguments to the cObject referenced by the TS view helper. Add arguments like in any other view helper by separating them with a pipe character |. The arguments are then available in cObject's the data array, they are called argument_[argument position]. Argument position is the position/number of the argument starting with 0.
Example:
###TS:lib.some.text.object|Foo|Bar|Baz###
lib.some.text.object = TEXT
lib.some.text.object {
field = argument_0 // Foo
field = argument_1 // Bar
field = argument_2 // Baz
}
