Community Wiki
Page tree
Skip to end of metadata
  • Created on 2016-04-07, last edited by Richard Gange on 2016-12-07
Go to start of metadata

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

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.

  1. Locate the example index found here /modules/content-indexer/config/indexers/websiteIndexer.
  2. 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

  1. Duplicate /modules/content-indexer/config/indexers/websiteIndexer.
  2. Rename the duplicated index to websiteIndexer_de to signify it's the German content indexer.
  3. Change the value of the type property to website_de.

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

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

  2. 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
  3. There is also a confirmation of successful indexing shown in the UI at the bottom of admincentral using a INFO type banner message.

  4. Finally you should see a new indexed property at both indexing configurations websiteIndexer and websiteIndexer_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.

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

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


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

    1. Add a page title set to Travel Solr Search Results

    2. Change the page dialog to use solr-search-provider:pages/pageProperties

    3. Change the templateId of the auto-generated component to use solr-search-provider:components/solrSearchResult

    4. Change the headline of the auto-generated component to Solr Powered Search Results

      solrSearchResultPage.yaml
      title: 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
  4. Make the new template available in the travel site definition using the Site app.
    1. Duplicate the node /travel/templates/availability/templates/searchResultPage
    2. Rename it to solrSearchResultPage
    3. Change the id to travel-demo:pages/solrSearchResultPage

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.

  1. In the Resources app locate the page dialog used by the travel demo website here /travel-demo/dialogs/pages/pageProperties.yaml
  2. Click Edit file.
  3. Locate the tabSearch portion of the dialog definition and set the i18n property to true on the searchResultPage field.

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

  1. Create a new web page for English search results called solr-search-results-en
  2. Create a new web page for German search results called solr-search-results-de

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

  1. Open solr-search-results-en for editing. Open the page properties dialog for the English Results page and set the filter field to type:website.
  2. Open solr-search-results-de for editing. Open the page properties dialog for the German Results page and set the filter field to type: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.

  • No labels

2 Comments

  1. Mathias Conradt

    Re: 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.

    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.

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