Magnolia search functionality is provided by the Jackrabbit repository. An indexer extracts text from nodes and properties. The content of pages, content apps and documents is included in the index.
Magnolia provides a transparent, preconfigured indexing configuration for administrators and for front-end developers which allow them to implement search with a FreeMarker script.
The Magnolia Travels demo site includes a complete search example, including displaying content stored in a content app in search results.
How search indexing works
Indexing is the process of collecting and parsing content, and storing the data in an index to make information retrieval fast and accurate.
Magnolia search is based on the default Jackrabbit search implementation. Jackrabbit uses an Apache Lucene-based indexer to process the data stored in the JCR. An index makes it faster to retrieve requested portions of the data. Node names and property values are indexed immediately and stored in the repository. Text from documents is extracted in a background process which makes document content searchable after a short delay.
You can find the physical index folders and files on the file system in
/<CATALINA_HOME>/webapps/<contextPath>/repositories/magnolia/workspaces/*/index. See the Jackrabbit Search wiki to learn how to configure search indexing from scratch and more about the options available with the implementation. The
workspace.xml file mentioned on the wiki is in
/repositories/magnolia/workspaces/<name of workspace>.
Typically, each Magnolia instance has its own repository and its own index. This means that the author instance index is typically different from public instance indexes. Any content that has not been activated to a public instance cannot be found when running a search on that public instance.
Magnolia index configuration
Magnolia uses a custom Jackrabbit/Lucene indexing configuration. The indexing configuration file is in the Magnolia Core module in
org.apache.jackrabbit.core.query.lucene.SearchIndex gets it from the classpath.
A generic Magnolia configuration is used for all workspaces. This configuration fine-tunes the default Jackrabbit search configuration for best results. The sections that follow detail the enhancements.
Jackrabbit stores all character data (node names and values) in Unicode. This ensures that special characters such as accents and umlauts are indexed and can be used in search. Issues with special characters are often due to character set conversion problems in the application server. See URI encoding in Tomcat for more.
Magnolia typically stores many properties, such as author, modification dates, templates etc., that are not relevant in search results. To minimize the index and speed-up search, all properties starting with
are excluded from the index. This means you get fewer results but those results are more relevant.
Boosting title property
The configuration boosts the
title property of the
mgnl:page node type since page titles are important.
Including areas and components
The configuration uses index aggregates to ensure area and component content is included in the index. The properties of
mgnl:component make up most of the contents of a page and need to be included explicitly. The aggregate also simplifies searching for content within pages.
Nested areas are also included using the
Providing excerpts and highlighting search results
workspace.xml file in each workspace enables highlighting in search results and the Jackrabbit HTML excerpt provider class. The
workspace.xml files are in
Here's the relevant extract from
workspace.xml in the
If you have used fields which allow for the storing of HTML, then that HTML will be indexed along with content. There is potential for the excerpt to contain HTML tags which are not closed.
Implementing search using templating functions
There are many ways to implement search on a site. This section explains how to do it using templating functions and uses the Magnolia Travels demo site as an example. If the demo modules are not installed your can download the
magnolia-travel-demo-parent module and install the demo and tours modules.
The MTE module provides search templating functions that allow front-end developers to render search results using only a template script. A component model or Java knowledge is not required. This is how search is implemented in the Magnolia Travels demo site.
There are methods for searching pages and other content, such as content stored in content apps. The methods are exposed in templates as
searchfn and you can find templating examples at searchfn.
All you need to implement search on a site is a component to retrieve the results from the search index and display them on the page.
This is how search works on the Magnolia Travels demo site.
searchResultscomponent (Git) searches pages and content apps for relevant results.
searchResults.ftl(Git) renders this component.
searchResultsPagetemplate (Git) autogenerates the
- Search results display on the
/travel/meta/search-resultspage that is based on the
/search-resultspage is assigned as the search page for the site in the
Displaying pages in the website workspace
searchPages method displays pages stored in the
website workspace in the search results. This method retrieves pages whose content (text, image and other properties) was added manually in the Pages app, as opposed to content retrieved from an app or another source. Set the root path of the site to return the relevant items.
Here's the snippet from
searchResults.ftl in the travel demo. The root path is
Displaying content stored in apps
searchContent method allows you to in the JCR. The method is useful to display "pages" whose content is stored in another workspace. In this scenario you need to set the workspace where the content is stored, the parent URL within that workspace and the node type.
In the Magnolia Travels demo site all Tour content (text, images and more) is entered in the Tours app and retrieved by a component that displays the content on pages. The app content is stored in the
tours workspace, under
/magnolia-travels and is of node type
Here's the snippet from
searchResults.ftl that retrieves Tours app content.
Here are the results for the term "swiss".
URI mapping is used in the Demo Travels example to display app content on pages and ensure that the content is included in the search index. URI mapping is a way to redirect incoming requests to the location of the content.
Configuring URI2Repository mapping
The URI mapping mechanism determines which repository node should be served when a particular URI is requested.
Here's the URI2Repository mapping for the
tours workspace in
|Injects the |
|Repository the mapping applies to.|
Configuring VirtualURI mapping
Virtual URI mapping allows you to create short, convenient URLs.
Here's the virtual URI mapping for the Tours app in
|RegexpVirtualURIMapping allows you to specify a regexp pattern that matches a sequence of characters. A pattern can match a variety of URIs.|
|Path to tours in the |
|URI to which tours are forwarded. |
You can customize search by writing your own queries to search the index and execute them in code. A query returns a result set which you can display on a page.
You can test your queries in the Query subapp. When you get the result set you want, implement the query in code.
The following queries are written in SQL-2. See JCR Query Cheat Sheet for more examples.
1) Find pages that contain the word "swiss".
3) Find assets that are not JPG images under the
/example path in the DAM.
Joins are slow in JCR SQL-2. See Queries in Jackrabbit 2.4.x for issue description and hints.
Search within Magnolia is access controlled. Search results include only content the user has permission to access. Permissions are controlled through Security. When you execute a query in Magnolia context ( MgnlContext ), contextual factors such as the current user's permissions are taken into account. If you do not have permission to the items you are querying, they will not show up in the results.
For more advanced search options you can use the Solr module. This module uses the Apache Solr search platform to index and crawl Magnolia content. Solr is a standalone enterprise search server with a REST like API. Solr uses the Lucene library for full-text indexing and provides advanced features such as faceted search, distributed search and index replication.