Apache Solr for TYPO3 CMS

h1. tx_solr.search

The search section, you probably already guessed it, provides configuration options for the all things related to actually searching the index, setting query parameters, formatting and processing result documents and the result listing.

{{toc}}

h2. filter

*Since:* version:1.0

*Default:*

*Type:* String

Adds additional parameters to the search initialization.

h2. targetPage

*Since:* version:1.0

*Default:* 0

*Type:* Integer

Sets the target page ID for links. If it is empty or 0, the current page ID will be used.

h2. initializeWithEmptyQuery

*Since:* version:1.4

*Default:* 0

*Options:* 0,1

*Type:* Boolean

If enabled, the results plugin (pi_results) issues a "get everything" query during initialization. This is useful, if you want to create a page that shows all available facets although no search has been issued by the user yet. Note: Enabling this option alone will not show results of the get everything query. To also show the results of the query, see option showResultsOfInitialEmptyQuery below.

h2. showResultsOfInitialEmptyQuery

*Since:* version:1.4

*Default:* 0

*Options:* 0,1

*Type:* Boolean

Requires initializeWithEmptyQuery (above) to be enabled to have any effect. If enabled together with initializeWithEmptyQuery the results of the initial "get everything" query are shown. This way, in combination with a filter you can easily list a predefined set of results.

h1. query

The query sub-section defines a few query parameters for the query that will be sent to the Solr server later on. Some query parameters are also generated and set by the extension itself, f.e. when using facets.

h2. query.allowEmptyQuery

*Since:* version:1.4

*Default:* 0

*Options:* 0,1

*Type:* Boolean

If enabled, empty queries are allowed.

h2. query.fields

*Since:* version:1.0

*Default:* content^40.0, title^5.0, keywords^2.0, tagsH1^5.0, tagsH2H3^3.0, tagsH4H5H6^2.0, tagsInline^1.0

*Type:* String

Defines what fields to search in the index. Fields are defined as a comma separated list. Each field can be given a boost by appending the boost value separated by the ^ character, that's Lucene query language. The boost value itself is a float value, pay attention to using a dot as the separator for the fractions. Use this option to add more fields to search.

The boost take influence on what score a document gets when searching and thus how documents are ranked and listed in the search results. A higher score will move documents up in the result listing. The boost is a multiplier for the original score value of a document for a search term.

By default if a search term is found in the content field the documents gets scored / ranked higher as if a term was found in the title or keywords field. Although the default should provide a good setting, you can play around with the boost values to find the best ranking for your content.

h2. query.minimumMatch

*Since:* version:1.2, version:2.0

*Default:* (empty)

*See:* http://wiki.apache.org/solr/DisMaxRequestHandler#mm_.28Minimum_.27Should.27_Match.29

*Type:* String

Sets the minimum match _mm_ query parameter.

By default the mm query parameter is set in solrconfig.xml as _2<-35%_. This means that for queries with less than three words they all must match the searched fields of a document. For queries with three or more words at least 65% of them must match rounded up.

Please consult the link to the Solr wiki for a more detailed description of the mm syntax.

h2. query.boostFunction

*Since:* version:1.2, version:2.0

*Default:* (empty)

*See:* http://wiki.apache.org/solr/DisMaxRequestHandler#bf_.28Boost_Functions.29

*Type:* String

Sets the boost function _bf_ query parameter.

Allows to further manipulate the score of a document by using mathematical functions and field values of the current document.

A common use case for boost functions is to rank newer documents higher than older ones.

Please consult the link to the Solr wiki for a more detailed description of boost functions.

h1. results

h2. results.siteHighlighting

*Since:* version:2.0

*Default:* 0

*Type:* Boolean

Activates TYPO3's highlighting of search words on the actual pages. The words a user searched for will be wrapped with a span and css class @csc-sword@

Highlighting can be styled using the CSS class @csc-sword@, you need to add the style definition yourself for the complete site.

h2. results.resultsPerPage

*Since:* version:1.0

*Default:* {$plugin.tx_solr.search.results.resultsPerPage}

*Type:* Integer

Sets the number of shown results per page.

h2. results.resultsPerPageSwitchOptions

*Since:* version:1.0

*Default:* 10, 20, 30, 50

*Type:* String

Defines the shown options of possible results per page.

h2. results.fieldProcessingInstructions

*Since:* version:1.0

*Options:* timestamp, utf8Decode, skip

*Type:* cObject

Mapping of fieldname to processing instructions. Available instructions: timestamp, utf8Decode, skip (removes the field from the result).

h2. results.fieldRenderingInstructions

*Since:* version:1.0

*Type:* cObject

Additional rendering instructions for specified fields.

h2. results.pagebrowser.templateFile

*Since:* version:1.0

*Default:* EXT:solr/resources/templates/pi_results/pagebrowser.htm

*Type:* String

Defines the template used for the pagebrowser.

h2. results.ignorePageBrowser

*Since:* version:1.0

*Default:* 0

*Options:* 0, 1

*Type:* Boolean

If enabled, the selected page will be ignored an results by the first record.

h2. results.showDocumentScoreAnalysis

*Since:* version:2.0

*Default:* 0

*Options:* 0,1

*Type:* Boolean

If enabled, the analysis and display of the score analysis for logged in backend users will be initialized.

h2. results.markResultTypeBoundaries

*Since:* version:2.0, version:2.5-dkd

*Default:* 0

*Options:* 0,1

*Type:* Boolean

This option allows for some kind of fake or client side (EXT:solr being the client) grouping of results. First you need to sort results by the type field. Then whenever the type field changes during rendering of the results, special fields are added to the documents at the result document type boundary. In your template you can then use an IF condition to insert markup at those boundaries based on those fields' values. The special document field names are "typeBegin" and "typeEnd". They have a value set to the new/old document type appended with "_begin"/"end".

Example:

A result set with documents of types tt_news, pages, and tt_address:

<pre>

1 pages      -> typeBegin = pages_begin

2 pages

3 pages      -> typeEnd   = pages_end

4 tt_address -> typeBegin = tt_address_begin

5 tt_address

6 tt_address -> typeEnd   = tt_address_end

7 tt_news    -> typeBegin = tt_news_begin

8 tt_news

9 tt_news    -> typeEnd   = tt_news_end

</pre>

h1. highlighting

h2. highlighting

*Since:* version:1.0

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.highlighting = 1@ to enable search term highlighting.

h2. highlighting.highlightFields

*Since:* version:1.0

*Default:* title,content

*Type:* String

Should be a comma- or space-delimited list of fields to generate highlighted snippets for.

h2. highlighting.fragmentSize

*Since:* version:1.0

*Default:* 200

*Type:* Integer

The size, in characters, of fragments to consider for highlighting. "0" indicates that the whole field value should be used (no fragmenting).

h2. highlighting.wrap

*Since:* version:1.0

*Default:* <span class="results-highlight">|</span>

*Type:* String

This is used to format the highlighted parts.

h1. spellchecking

h2. spellchecking

*Since:* version:1.0

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.spellchecking = 1@ to enable spellchecking / did you mean.

h2. spellchecking.wrap

*Since:* version:1.0

*Default:* |<div class="spelling-suggestions">###LLL:didYouMean### |</div>|

*Type:* String

This is used to format spelling suggestions.

h1. lastSearches

h2. lastSearches

*Since:* version:1.3-dkd

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.lastSearches = 1@ to display a list of the last searches.

h2. lastSearches.limit

*Since:* version:1.3-dkd

*Default:* 10

*Type:* Integer

Defines the number of last searches, that should get minded.

h2. lastSearches.mode

*Since:* version:1.3-dkd

*Default:* user

*Options:* user, global

*Type:* String

If mode is user, keywords will get stored into the session. If mode is global keywords will get stored into the database.

h1. commonTerms

h2. commonTerms

*Since:* version:1.3-dkd

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.commonTerms = 1@ to display a list of the frequent / common searches.

h2. commonTerms.minSize

*Since:* version:1.3-dkd

*Default:* 14

*Type:* Integer

The difference between commonTerms.maxSize and commonTerms.minsize is getting used for calculating the current step.

h2. commonTerms.maxSize

*Since:* version:1.3-dkd

*Default:* 32

*Type:* Integer

The difference between commonTerms.maxSize and commonTerms.minsize is getting used for calculating the current step.

h2. commonTerms.limit

*Since:* version:1.3-dkd

*Default:* 20

*Type:* Integer

Defines the maximum size of the list by commonTerms.select.

h2. commonTerms.select

*Since:* version:1.3-dkd

*Type:* cObject

Defines a database connection for retrieving statistics.

h1. sorting

h2. sorting

*Since:* version:1.0

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.sorting = 1@ to allow sorting of results.

h2. sorting.defaultOrder

*Since:* version:1.0

*Default:* ASC

*Options:* ASC, DESC

*Type:* String

Sets the order of sortings.

h2. sorting.fields

This is a list of fields configured to be used for sorting. Each field has a label to be used, the label more specifically is a LLL key. By default the fields sortTitle, type, sortAuthor, and created are configured, plus the virtual relevancy field which is used for sorting by default.

h3. sorting.fields.[sortField].label

*Since:* version:1.0

*Type:* String

Defines the name of the field's label.

h1. faceting

h2. faceting

*Since:* version:1.0

*Default:* 0

*Type:* Boolean

Set @plugin.tx_solr.faceting = 1@ to enable faceting.

h2. faceting.minimumCount

*Since:* version:1.0

*Default:* 1

*Type:* Integer

*See:* http://wiki.apache.org/solr/SimpleFacetParameters#facet.mincount

This indicates the minimum counts for facet fields should be included in the response.

h2. faceting.sortBy

*Since:* version:1.0

*Default:* count

*Options:* count, index, 1, 0, true, false, alpha (version:1.2, version:2.0), lex (version:1.2, version:2.0)

*See:* http://wiki.apache.org/solr/SimpleFacetParameters#facet.sort

*Type:* String

Defines how facet options are sorted, by default they are sorted by count of results, highest on top. count, 1, true are aliases for each other.

Facet options can also be sorted alphabetically (lexicographic by indexed term) by setting the option to index. index, 0, false, alpha (from version version:1.2 and version:2.0), and lex (from version version:1.2 and version:2.0) are aliases for index.

h2. faceting.limit

*Since:* version:1.0

*Default:* 10

*See:* http://wiki.apache.org/solr/SimpleFacetParameters#facet.limit

*Type:* Integer

This indicates the maximum number of constraint counts that should be returned for the facet fields. A negative value means unlimited.

h2. faceting.singleFacetMode

*Since:* version:1.2, version:2.0

*Default:* 0

*Options:* 0, 1

*Type:* Boolean

If enabled, the user can only use one facet at a time. 

Lets say you have you have two facets configured, type and author. If the user selects a facet option from type its filter is added to the query. Normally when selecting another option from the other facet - the author facet - this would lead to having two facet filters applied to the query. When this option is activated the option from the author facet will simply replace the first option from the type facet.

h2. faceting.removeFacetLinkText

*Since:* version:1.0

*Default:* @facetText (remove)

*Type:* String

Defines the text for a link used for removing a given facet from the search results.

h2. faceting.showAllLink.wrap

*Since:* version:1.0

*Default:* <li>|</li>

*Type:* String

Defines the output of the "Show more" link, that is rendered if there are more facets given than set by faceting.limit.

h2. faceting.showEmptyFacets

*Since:* version:1.3

*Default:* 1

*Options:* 0, 1

*Type:* Boolean

By setting this option to 0, you can prevent rendering of empty facets. Usually, although a facet does not offer any options to filter a set of result documents, the facet header might still be shown depending on the template. Using this option prevents the header from appearing when no filter options are provided.

h2. faceting.facetLinkATagParams

*Since:* version:2.0

*Type:* String

With this option you have the possibility to add A-Tag attributes for links of all facet-options.

<pre><code class="typoscript">

    plugin.tx_solr.search.faceting.facetLinkATagParams = class="green"

</code></pre>

h2. faceting.facets

*Since:* version:1.0

*Default:* type, author

*See:* http://wiki.apache.org/solr/SolrFacetingOverview

*Type:* cObject

Defines on which fields you want to facet. It's a list of facet configurations.

<pre><code class="typoscript">

plugin.tx_solr.search.faceting.facets {

    // type is the name of the facet configuration, you can choose whatever name

  type {

    field = type // the index field you want to create a facet from

    label = Content Type // a label

    sortBy = index // sorte the facet options alphabetically, otherwise they are sorted by count, options with more results on top

    keepAllOptionsOnSelection = 1 // if set allows to choose more than one option from this facet

    operator = OR // used in combination with keepAllOptionsOnSelection to set how multiple options from one facet are combined, can also be AND

    selectingSelectedFacetOptionRemovesFilter = 1 // boolean; if enabled, the facet options behave like switches. On first selection they add the filter for the facet option, on a second click they will remove the filter again. Currently requires keepAllOptionsOnSelection to be set to use this.

  }

  myOtherFacet {

    ...

  }

}

</code></pre>

h2. faceting.facets.[facetName] - single facet configuration

You can add new facets by simply adding a new facet configuration in TypoScript. [facet] represents the facet's name and acts as a configuration "container" for a single facet. All configuration options for that facet are defined within that "container".

A facet will use the values of a configured index field to offer these values as filter options to your site's visitors. You need to make sure that the facet field's type allows to sort the field's value; like string, int, and other primitive types.

h3. faceting.facets.[facetName].field

*Since:* version:1.0

*Type:* String

*Required*

Which field to use to create the facet.

h3. faceting.facets.[facetName].label

*Since:* version:1.0

*Type:* String

*Required*

Used as a headline or title to describe the options of a facet.

h3. faceting.facets.[facetName].selectingSelectedFacetOptionRemovesFilter

*Since:* version:1.2, version:2.0

*Default:* 0

*Options:* 0, 1

*Type:* Boolean

Activating this option for a facet makes the facet's option links behave like on/off switches: You click them once to activate a facet, you click them a second time to deactivate the facet again.

Feel free to suggest a better name for this option...

h3. faceting.facets.[facetName].keepAllOptionsOnSelection

*Since:* version:1.2, version:2.0

*Default:* 0

*Options:* 0, 1

*Type:* Boolean

Normally, when clicking any option link of a facet this would result in only that one option being displayed afterwards. By setting this option to one, you can prevent this. All options will still be displayed. 

This is useful if you want to allow the user to select more than one option from a single facet.

h3. faceting.facets.[facetName].singleOptionMode

*Since:* version:1.3, version:2.0

*Default:* 0

*Options:* 0, 1

*Type:* Boolean

When enabled together with keepAllOptionsOnSelection a user can select one option of the facet only at a time. Selecting a different option than the currently selected option results in the new option to replace the old one. The behavior thus is similar to a select box or a set of radio buttons.

This option can not be used together with selectingSelectedFacetOptionRemovesFilter as it overrides its behavior.

h3. faceting.facets.[facetName].operator

*Since:* version:1.2, version:2.0

*Default:* AND

*Options:* OR, AND

*Type:* String

When configuring a facet to allow selection of multiple options, you can use this option to decide whether multiple selected options should be combined using AND or OR.

h3. faceting.facets.[facetName].sortBy

*Since:* version:1.2

*Default:* -

*Options:* alpha (aliases: index, lex)

*Type:* String

Sets how a single facet's options are sorted, by default they are sorted by number of results, highest on top.

Facet options can also be sorted alphabetically by setting the option to alpha.

h3. faceting.facets.[facetName].includeInAvailableFacets

*Since:* version:1.3

*Default:* 1

*Options:* 0, 1

*Type:* Boolean

By setting this option to 0, you can prevent rendering of a given facet within the available facets list.

This is pretty helpful if you render the facet yourself using a view helper and don't want the facet to be rendered twice.

h3. faceting.facets.[facetName].renderer

*Since:* version:1.6-dkd

*Type:* Class name

Defines an alternative renderer class for a facet. The class must implement interface tx_solr_FacetRenderer

Available facet types / renderers:

*  tx_solr_facet_HierarchicalFacetRenderer - render hierarchical facets, indexed using the "pathToHierarchy" [[Tx_solrindex#fieldProcessingInstructions|field processing instruction]]

* tx_solr_facet_DateRangeFacetRenderer - renders two date input fields with date picker

h3. faceting.facets.[facetName].filterParser

*Since:* version:1.7-dkd

*Type:* Class name

A class name that is used to create a filter parser to turn filter GET parameter generated by a facet renderer (see above) into a Lucene filter. This is useful to have a more readable filter GET parameter in the URL, but sill being able to use Lucene filters internally.

Available filter parser:

* tx_solr_query_filterparser_DateRange - resolve a date range filter created by tx_solr_facet_DateRangeFacetRenderer

<pre>

Example:

URL GET parameter for a date range as generated by tx_solr_facet_DateRangeFacetRenderer:

dateCreated:200910010000-201107012359  (format is YYYYMMDDHHMM)

Transformed into a Lucene filter by tx_solr_query_filterparser_DateRange:

created:[2009-10-01T00:00:00Z TO 2011-07-01T23:59:59Z]

</pre>

h3. faceting.facets.[facetName].renderingInstruction

*Since:* version:1.0

*Type:* cObject

Overwrites how single facet options are rendered using TypoScript cObjects. 

Example: (taken from issue #5920)

<pre><code class="typoscript">

plugin.tx_solr {

    search {

        faceting {

            facets {

                type {

                    renderingInstruction = CASE

                    renderingInstruction {

                        key.field = optionValue

                        pages = TEXT

                        pages.value = Pages

                        pages.lang.de = Seiten

                        file = TEXT

                        file.value = Files

                        file.lang.de = Dateien

                        tt_news = TEXT

                        tt_news.value = News

                        tt_news.lang.de = Nachrichten

                    }

                }

                language {

                    renderingInstruction = CASE

                    renderingInstruction {

                        key.field = optionValue

                        0 = TEXT

                        0.value = English

                        0.lang.de = Englisch

                        1 = TEXT

                        1.value = German

                        1.lang.de = Deutsch

                    }

                }

            }

        }

    }

}

</code></pre>

h3. faceting.facets.[facetName].facetLinkATagParams

*Since:* version:2.0

*Type:* String

With this option you have the possibility to add A-Tag attributes for all option-links of a single facet.

This option overwrites the global setting "faceting.facetLinkATagParams".

Check up "faceting.facetLinkATagParams" for more information.