Summary
In this tutorial we will walk through the steps necessary to integrate Magnolia 5.4.6 with Solr 5.5.0. Once integrated we will see how to create localized search pages for a multi-language website. In this case we will use the travel demo website provided with Magnolia CMS as the example website. The travel demo website is a single-site-multi-language example where we will use filters to filter out one language when searching for content in the other. If you have any issues or questions about the tutorial please comment at the bottom of the page.
Prerequisites
- Magnolia 5.4.5+ EE: 5.4 Releases
- Magnolia Solr 5.0.2 Content Indexer Module: https://documentation.magnolia-cms.com/display/DOCS/Solr+module
- Magnolia Solr 5.0.2 Search Provider Module: https://documentation.magnolia-cms.com/display/DOCS/Solr+module
- Apache Solr 5.5.0: http://archive.apache.org/dist/lucene/solr/5.5.0/
Set up
Install Apache Solr
Apache Solr is a standalone search server. Download Apache Solr and extract the zip to your computer. See Solr module for more instructions on installing Solr 5. These instructions also cover creating a core for your Magnolia instance so be sure to complete all steps.
Install Magnolia with Solr Modules
This tutorial is using Magnolia 5.4.6 bundle. However, another version should also be fine or a Magnolia running in your IDE should also work as well.
Be sure to also install the required Magnolia Solr models as they are not part of the standard bundle. You can either download them from our nexus or include them as dependencies in your Maven project. See Solr module for more.
This tutorial also requires that the travel demo be installed but this is not a hard requirement. You may want to use it as a guide for indexing your own website.
I do recommend working through this tutorial using the travel demo first if you are new to Magnolia.
Indexing website content
We need to configure a separate index for each language served by the demo site. The Magnolia Content Indexer module will provide you with an example of how to index content located in the website workspace. That example can be found here /modules/content-indexer/config/indexers/websiteIndexer
.
Create a default index
The default index will index the content for our default language. In the case of the travel demo that would be the English content.
- Locate the example index found here
/modules/content-indexer/config/indexers/websiteIndexer
. - Set the
rootNode
property to/travel
.
Field mappings
The field mappings defines how Magnolia content properties are mapped to Solr fields. Left side is Magnolia, right side is Solr. Essentially we are telling Solr which properties we would like to index. These properties get mapped to fields in Solr documents.
In our example indexer there are some field mappings set up for you. For the tutorial we'll use these mappings.
Depending on your project you may want to add additional fields. The default mappings probably do not cover every property you want to index on your pages.
You can use the fields available in the schema. If a field does not exist in Solr's schema you can use a dynamic field mgnlmeta_*
. For instance if you have information nested in a deep leaf of your page stored with property specComponentAbstract
, you can map this field with mgnlmeta_specComponentAbstract
. The indexer contains a recursive call which will explore the node's child leaves until it finds the property.
Create a German content index
- Duplicate
/modules/content-indexer/config/indexers/websiteIndexer
. - Rename the duplicated index to
websiteIndexer_de
to signify it's the German content indexer. - Change the value of the
type
property towebsite_de
. Change the names and values of all field mappings to have the suffix
_de
.
Adding the
_de
suffix to the names of the field mappings will instruct Solr to look for those properties which store German content in a single-site-multi-language implementation. See Storing and serving localized content for more information on how multi-language data is stored in a single tree structure.
Trigger the initial indexing
To trigger the initial indexing of the content set the
enabled
property to true on both indexing configurations.I make the assumption that you have Solr running on port 8983 at http://localhost:8983/solr/. If you have some other setup then you need to see the section on Configuring the Solr server base URL in our Solr module documentation.
Watch the log file for the following messages of indexing confirmation.
2016-05-20 13:27:04,755 INFO info.magnolia.module.ModuleManagerImpl : Stopping module content-indexer 2016-05-20 13:27:04,765 INFO info.magnolia.module.ModuleManagerImpl : Starting module content-indexer 2016-05-20 13:27:06,513 INFO info.magnolia.module.indexer.DataIndexer : [websiteIndexer]: 33 pages indexed in 1344 ms 2016-05-20 13:27:11,540 INFO info.magnolia.module.ModuleManagerImpl : Stopping module content-indexer 2016-05-20 13:27:11,547 INFO info.magnolia.module.ModuleManagerImpl : Starting module content-indexer 2016-05-20 13:27:12,510 INFO info.magnolia.module.indexer.DataIndexer : [websiteIndexer_de]: 33 pages indexed in 938 ms 2016-05-20 13:27:17,529 INFO info.magnolia.module.ModuleManagerImpl : Stopping module content-indexer 2016-05-20 13:27:17,541 INFO info.magnolia.module.ModuleManagerImpl : Starting module content-indexer
- There is also a confirmation of successful indexing shown in the UI at the bottom of admincentral using a INFO type banner message.
Finally you should see a new
indexed
property at both indexing configurationswebsiteIndexer
andwebsiteIndexer_de
. You may need to refresh the node to see the property. A simple close-open toggle of the indexer configuration node should do the trick in making it appear.
You can always trigger the indexing mechanism by setting the
indexed
property to false and waiting a few seconds for the confirmation.
Create a search results template
Most likely your website already has a design in-place or is in-the-works. This is the case with our travel demo site. It has a search results template already available. All we need to do is make a Solr version of this template. On the other hand if you're just getting started with Magnolia there are some example page templates provided by the Search Provider module. See Creating a search results page for both MTE and STK examples.
Locate the travel demo search results template here
/travel-demo/templates/pages/searchResultPage.yaml
.This file is found in the
resources
workspace using the Resource Files app.Make a copy of the existing template and use it to create a Solr version.
Notice my copy exists in the
resources
workspace. This is indicated by the JCR icon in the Origin column of the Resource Files app. This is fine for the tutorial but ideally you would want to create your template in a custom module.
The Magnolia Search Provider module provides us with a page dialog (
/modules/solr-search-provider/dialogs/pages/pageProperties
) and search result component (/modules/solr-search-provider/templates/components/solrSearchResult
) that we can use in our search results page template.Add a page
title
set to Travel Solr Search ResultsChange the page
dialog
to usesolr-search-provider:pages/pageProperties
Change the
templateId
of the auto-generated component to usesolr-search-provider:components/solrSearchResult
Change the
headline
of the auto-generated component to Solr Powered Search ResultssolrSearchResultPage.yamltitle: Travel Solr Search Results dialog: solr-search-provider:pages/pageProperties class: info.magnolia.templating.definition.PageTemplateDefinition renderType: site type: feature areas: main: templateScript: /travel-demo/templates/pages/areas/contentContainerSingle.ftl type: single parameters: cssClass: container autoGeneration: generatorClass: info.magnolia.rendering.generator.CopyGenerator content: singleton: nodeType: mgnl:component templateId: solr-search-provider:components/solrSearchResult headline: Solr Powered Search Results footer: editable: false
- Make the new template available in the travel site definition using the Site app.
- Duplicate the node
/travel/templates/availability/templates/searchResultPage
- Rename it to
solrSearchResultPage
- Change the
id
totravel-demo:pages/solrSearchResultPage
- Duplicate the node
Create the search results pages
For this tutorial we will use the approach of a separate search results page for each language. In this case two pages, one for English results and one for German results.
Internationalize the result page link field
The travel demo has a special page dialog for the page templates used within it's site. This dialog provides a field for the location of the search results page. Since we will have two results pages, one for each language we must internationalize the field to accommodate this.
- In the Resources app locate the page dialog used by the travel demo website here
/travel-demo/dialogs/pages/pageProperties.yaml
- Click Edit file.
- Locate the
tabSearch
portion of the dialog definition and set thei18n
property to true on thesearchResultPage
field.
Save changes.
For the tutorial it's quite easy to just edit the dialog from the Resources app. In a real project you would want to edit the dialog definition located inside your module.
Create the search results pages
The travel demo keeps it's search result page under the meta section of the website here /travel/meta/search-results
. We'll follow the same convention.
- Create a new web page for English search results called
solr-search-results-en
- Create a new web page for German search results called
solr-search-results-de
Open the Travel Home page for editing. Open the page properties dialog for the Travel Home page and set the search results pages for each language.
The search result page must be configured on the home (or root) page of the website. Even though the entire travel demo uses the same page dialog for every page, the search mechanism will look for the configured results pages on the home (root) of the site.
Configure the search results pages
Each search result page needs to be configured for the language it supports using a filter. This is done through the page dialog of each result page in the Additional filters field.
- Open
solr-search-results-en
for editing. Open the page properties dialog for the English Results page and set the filter field totype:website
.
- Open
solr-search-results-de
for editing. Open the page properties dialog for the German Results page and set the filter field totype:website_de
.
Test it out
Try performing some searches. For example search the term "unique" on both the English and German travel sites. You should only find matches in the English site. Likewise try searching the term "beispielprojekt" on both sites. You should not find any matches on the English site.
Troubleshooting
Sometimes re-indexing can help clear issues. In rare cases rebuilding the entire core seemed to help. This is especially true in you had started this project in earlier versions of the Magnolia Solr modules. Localization support was not added until 5.0.2.
2 Comments
Mathias Conradt
Does this refer to bundle version vs. non-bundle version or also to other minor versions of Magnolia or even Magnolia CE, i.e. would it work with Magnolia CE 5.4.3 for example?
Would be great if the minimum version would be mentioned in this wiki article. It does say "Magnolia 5.4.6 EE" under prerequisites, but not sure if those are just the versions used in this tutorial, or really the actual minimum required versions in general.
Other than that, great feature! I was missing this in older versions, as I had mentioned on StackOverflow in 2015.
Update - to answer my own question: Ok, looking at the Solr module pages, i.e. Magnolia Solr 5.0.2 Content Indexer Module, I can see that it's only available in the enterprise edition.
Richard Gange
Hi Mathias-
Magnolia Solr module is compatible with EE std, so this would not apply to CE.
Yes, I did mention the Magnolia version I used. However, the restriction is the Solr module itself. You have to use 5.0.2 in order to do this. That requires Magnolia 5.4.5 EE Std at minimum.
HTH
Rich