Full text search with Solr

OpenCms 10 provides the content type "Search Configuration" (jsp-search), that is available in the "System elements" content view. It comes with a default formatter that already can handle all combination of configuration options. Just create a page where your search should be located and place a "Search Configuration" on it.

Open the content to see the available options:

Via the configuration content all configuration options for <cms:search> are available. The different tabs represent the different search features. To get an overview, just click through the tabs, have a look at the options and read the tooltips. They are the best documentation.

The option you may need in nearly all cases is "Additional Solr Query Parameters" in the tab "Query options". Here you should specify your site root as parent folder, and possibly the types of content you want to search. See the tooltip for the editor field on how to do this.

As long as you have not written an own formatter for jsp-search, the default formatter is used. It can handle all the options, but may not yield the output you want. Hence, you should write your own formatter.

Additionally to the search page itself, you may want a search slot on all your pages. It should only call the search page with the correct parameter to hand over the search word. The default parameter is q. If needed, you can change it under the "Query Options" -> "Request Parameter: Query".

The simplest way to implement a full-text search is to write a formatter for the jsp-search content, shipped with the OpenCms core in the module org.opencms.jsp.search and get your configuration right. For the formatter, you can start with the demo formatter referenced in the above section.

When you got everything correct, you rewrite your formatter JSP to be used for a dynamic function or a content type providing configuration options specific to your needs. The rewrite is very easy, since you only replace the confguration handed over to the <cms:search> tag. You may even keep your configuration content, or what might be more valueable, replace it with a JSON configurationThere's a one-to-one correspondence between the options in the XML content and in the JSON  configuration.. Everything else remains the same.

The formatter basically:

• hands over the jsp-search content (or later the JSON configuration) to the <cms:search> tag as configuration content (or string).
• explores the result object exposed by <cms:search> to build up the search form and render the search results.

The result exposed by <cms:search> is of type org.opencms.jsp.search.result.I_CmsSearchResultWrapper. A good explanation of its structure is given in the presentation of the tag on the OpenCms Days 2015. Moreover, you can explore the formatters for the full text search of

• the Mercury demo template shipped with OpenCms 10.0The formatter is located under /system/modules/alkacon.mercury.template/functions/search.jsp
• the search included in this documentationThe formatter is located under /system/modules/com.alkacon.opencms.documentation.searchform/formatters/searchform-formatter.jsp

as examples for using it.

Moreover, for the JSON configuration, an example JSON file with all options is found in the test cases for OpenCms here.

Besides the configuration via an XML content and the use of <cms:search> in the formatter of that content, the tag can be configured via a JSON configuration that can be provided either as file or as string. These configuration options are typically preferable not only for full-text serach, but also for implementing lists of content.

Using a JSON string is in particular valuable if you want to provide your own content type, or a dynamic function with element settings or parameters for rendering the search form. Then you can use the content elements, element settings and parameters to adjust the JSON string. The benefit is a fine-grained control on the configuration options that are exposed. Moreover, it becomes possible to change configuration depending on the seach state, e.g., you can make the search configurable by the end user.

The JSON configuration provides the same options as the XML configuration content. An example is found here. To get an overview on all the configuration options, please look at the (JavaDoc and source code of the) configuration parser org.opencms.jsp.search.config.parser.CmsJSONSearchConfigurationParser.

When your content is searchable, you should take care on how it is indexed. In particular, you should

• Set suitable search settings in the schema of XML contents
• Specify in formatter configurations if the content should be indexed for container pages as well