Search the documentation
 Show GitHub edit links  Hide GitHub edit links
In OpenCms since: 10.0 Documented since: 10.0 Latest revision for: 10.0 Valid for OpenCms: 10.5.2

Solr is a mighty tool to perform full text search with many of extra features, such as (various kinds of) facets, "Did you mean?" functionality and highlighting with suitable selection of text snippets for an extract.

Implementing a fully featured Solr search can be involved and time consuming. Up to OpenCms 9.5 a client side Solr search was integrated in the demo template shipped with OpenCms. Even partly configurable, it was hard to adjust for the use in other web sites. In particular, a lot of GWT code that handled the state of the search form and rendered the output had to be touched.

The complexity of implementing a client-side search function led to the decision to add support for a server side search. This will remove the complexity of writing client side code and might be sufficient for many purposes. With the tag <cms:search>, introduced in OpenCms 10, writing a full text search for a website is done within just a few minutes or hours. And this search already supports facets, highlighting, pagination, etc.

Adding a full text search to your webpage

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.

You do not need to configure any option you do not use. Even with no configuration at all, you have a, thought simple, full text search.

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".

Writing your own formatter for the full text search

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. The module provides a default formatter, located under /system/modules/org.opencms.jsp.search/formatters/jsp-search-formatter.jsp. Copy the formatter and adjust it to your needs. The default formatter includes a lot of comments that will help understanding it. Your copy can be much simpler if you do not need to support all options of <cms:search>.

The formatter basically:

  • hands over the jsp-search content to the <cms:search> tag as configuration content.
  • 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 Apollo demo template shipped with OpenCms 10.0The formatter is located under /system/modules/org.opencms.apollo.template.formatters/formatters/jsp-search-formatter.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.

Other ways to work with <cms:search>

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 for implementing lists of content, but can also be valuable for implementing a full text search.

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.

Preparing your content for the search

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

You can improve this page

Please contribute your suggestions or comments regarding this topic on our wiki. For support questions, please use the OpenCms mailing list or go for professional support.