Documentation Home

Module Installation

Steps to enable this module in your custom Broadleaf Commerce project

Steps

Step 1 Pull this dependency into your parent pom.xml:

In your properties section add:

        <broadleaf-enterprise-search.version>2.0.6-SNAPSHOT</broadleaf-enterprise-search.version>

In the dependency section add:

<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-enterprise-search</artifactId>
    <version>${broadleaf-enterprise-search.version}</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>

Data Changes

Schema Changes

To add all of the necessary database tables and columns for this module, please follow the Liquibase update documentation.

Admin Security Changes

The data in the following SQL file is required to establish Admin sections and permissions for this module:

classpath:/config/bc/sql/load_enterprise_search_admin_security.sql
classpath:/config/bc/sql/load_search_admin_security.sql

This file is automatically included if you have set blPU.hibernate.hbm2ddl.auto=create and you have not set import.sql.enabled=false in your properties files. If you are not using Hibernate's auto DDL process and are using Liquibase, you can add a new changeSet that references this file:

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.5.xsd">
    <changeSet author="broadleaf" id="some-unique-id">
        <sqlFile path="config/bc/sql/load_enterprise_search_admin_security.sql" encoding="utf8" stripComments="true" />
        <sqlFile path="config/bc/sql/load_search_admin_security.sql" encoding="utf8" stripComments="true" />
    </changeSet>
</databaseChangeLog>

Finally, you can unpack the downloaded .jar file and look at the files in the config/bc/sql folder to execute this sql manually.

Data Changes

  1. Include the following dynamicField's and fieldType's to your solr schema.xml:

    <dynamicField name="*_tta" type="text_type_ahead" indexed="true" stored="true"/>
<dynamicField name="*_tpa" type="text_partial" indexed="true" stored="true" />
<dynamicField name="*_tsl" type="text_soundslike" indexed="true" stored="true" />
<dynamicField name="*_tsy" type="text_synonyms" indexed="true" stored="true" />

<dynamicField name="*_tmg" type="text_managed_en" indexed="true" stored="true" />
<dynamicField name="*_tmg_en" type="text_managed_en" indexed="true" stored="true" />
<dynamicField name="*_tmg_es" type="text_managed_es" indexed="true" stored="true" />
<dynamicField name="*_tmg_fr" type="text_managed_fr" indexed="true" stored="true" />

<fieldType name="text_partial" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.WordDelimiterFilterFactory"
                generateWordParts="0"
                generateNumberParts="0"
                catenateWords="1"
                catenateNumbers="1"
                catenateAll="1"
                splitOnCaseChange="1"
                splitOnNumerics="0"
                preserveOriginal="1"
        />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.RemoveDuplicatesTokenFilterFactory"/>
        <filter class="solr.PorterStemFilterFactory"/>
        <filter class="solr.EdgeNGramFilterFactory" maxGramSize="20" minGramSize="2"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="([^\w\d\*æøåÆØÅ ])" replacement="" replace="all"/>
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.WordDelimiterFilterFactory"
                generateWordParts="0"
                generateNumberParts="0"
                catenateWords="0"
                catenateNumbers="0"
                catenateAll="0"
                splitOnCaseChange="0"
                splitOnNumerics="0"
                preserveOriginal="1"
        />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.PorterStemFilterFactory"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="([^\w\d\*æøåÆØÅ ])" replacement="" replace="all"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="^(.{20})(.*)?" replacement="$1" replace="all"/>
    </analyzer>
</fieldType>

<fieldType name="text_soundslike" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.DoubleMetaphoneFilterFactory" inject="true"/>
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.DoubleMetaphoneFilterFactory" inject="true"/>
    </analyzer>
</fieldType>

<fieldType name="text_synonyms" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.SynonymFilterFactory" synonyms="synonyms.txt" ignoreCase="true" expand="true" />
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.SynonymFilterFactory" synonyms="synonyms.txt" ignoreCase="true" expand="true" />
    </analyzer>
</fieldType>
<fieldType name="text_type_ahead" class="solr.TextField">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.WordDelimiterFilterFactory"
             generateWordParts="0"
             generateNumberParts="0"
             catenateWords="1"
             catenateNumbers="1"
             catenateAll="1"
             splitOnCaseChange="1"
             splitOnNumerics="0"
             preserveOriginal="1"
        />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.RemoveDuplicatesTokenFilterFactory"/>
        <filter class="solr.PorterStemFilterFactory"/>
        <filter class="solr.EdgeNGramFilterFactory" maxGramSize="20" minGramSize="2"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="([^\w\d\*æøåÆØÅ ])" replacement="" replace="all"/>
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.WordDelimiterFilterFactory"
             generateWordParts="0"
             generateNumberParts="0"
             catenateWords="0"
             catenateNumbers="0"
             catenateAll="0"
             splitOnCaseChange="0"
             splitOnNumerics="0"
             preserveOriginal="1"
        />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.PorterStemFilterFactory"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="([^\w\d\*æøåÆØÅ ])" replacement="" replace="all"/>
        <filter class="solr.PatternReplaceFilterFactory" pattern="^(.{20})(.*)?" replacement="$1" replace="all"/>
    </analyzer>
</fieldType>

<fieldType name="text_managed_en" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.ManagedStopFilterFactory" managed="en" />
        <filter class="solr.ManagedSynonymFilterFactory" managed="en" />
    </analyzer>
</fieldType>

<fieldType name="text_managed_es" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.ManagedStopFilterFactory" managed="es" />
        <filter class="solr.ManagedSynonymFilterFactory" managed="es" />
    </analyzer>
</fieldType>

<fieldType name="text_managed_fr" class="solr.TextField" positionIncrementGap="100">
    <analyzer type="index">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
    </analyzer>
    <analyzer type="query">
        <tokenizer class="solr.StandardTokenizerFactory" />
        <filter class="solr.LowerCaseFilterFactory" />
        <filter class="solr.ManagedStopFilterFactory" managed="fr" />
        <filter class="solr.ManagedSynonymFilterFactory" managed="fr" />
    </analyzer>
</fieldType>

Type Ahead Concepts

The type ahead functionality in the enterprise search module uses a custom Solr solution for delivering type ahead
suggestions. This is primarily done through using advanced filter factories, highlighting, and boosting.

The first aspect of the type ahead functionality comes from the use of advanced filter factories such as Solr's
EdgeNGramFilterFactory. This filter processes a term hot into edge ngrams h, ho, and hot. This is used by our
type ahead so that when the user types ho they end up matching a field that has the word hot, hoop, or horn.
This functionality is fairly powerful and allows for some complicated matching scenarios. For instance, ho sa would match
hot sauce and also match saddle horn.

The second aspect of the type ahead functionality comes from the use of Solr's highlighting engine. Simply put,
highlighting in Solr allows us to specify a field name and a query, which Solr processes and then returns the contents of that field
with the words matching that query surrounded with a denominator, typically ***. We then take these words and use them
as the suggestions for our type ahead.

The third aspect of the type ahead functionality comes from the use of boosting within Solr. We allow an admin user to
specify a boost value for each field we query against. This boost value influences the score (ordering) of the documents
(and highlighting suggestions) returned by Solr. Using boost values allows the user to give more weight to a match
against a product's name than a product's description.

Type Ahead Configuration

If you are using the type ahead functionality in your frontend website you will need to follow these steps:

  1. Add Type Ahead Configuration through admin or sql:

    If you choose to add the configuration through the admin or want to modify your type ahead configuration later, navigate to /admin/type-ahead.
    If you prefer to add the configuration using sql, here is an example insert from our demo data:

    INSERT INTO BLC_TYPE_AHEAD_CONFIG (TYPE_AHEAD_CONFIG_ID, ACTIVE_END_DATE, ACTIVE_START_DATE, CATEGORY_LIMIT, CATEGORY_SUGGESTIONS, FRAGMENT_SIZE, NAME, PHRASE_PROXIMITY, SEARCH_URL, SUGGESTION_LIMIT) VALUES  (-33000, NULL, CURRENT_TIMESTAMP, 5, TRUE, 30, 'Demo Type Ahead', 2, '/search', 8);

  2. Add type ahead fields to the set of indexed fields

    You will need to add in some index field entities to your application to be targeted by the type ahead search.
    This can be done withing the admin by going to /admin/search-field, or by sql like the following:

    -- Product Name Field
INSERT INTO BLC_INDEX_FIELD (INDEX_FIELD_ID, FIELD_ID, SEARCHABLE) VALUES (-33001, 4, FALSE);
INSERT INTO BLC_INDEX_FIELD_TYPE (INDEX_FIELD_TYPE_ID, INDEX_FIELD_ID, FIELD_TYPE) VALUES (-33001, -33001, 'tta');

-- Manufacturer Field
INSERT INTO BLC_INDEX_FIELD (INDEX_FIELD_ID, FIELD_ID, SEARCHABLE) VALUES (-33002, 1, FALSE);
INSERT INTO BLC_INDEX_FIELD_TYPE (INDEX_FIELD_TYPE_ID, INDEX_FIELD_ID, FIELD_TYPE) VALUES (-33002, -33002, 'tta');

-- Long Description Field
INSERT INTO BLC_INDEX_FIELD (INDEX_FIELD_ID, FIELD_ID, SEARCHABLE) VALUES (-33003, 7, FALSE);
INSERT INTO BLC_INDEX_FIELD_TYPE (INDEX_FIELD_TYPE_ID, INDEX_FIELD_ID, FIELD_TYPE) VALUES (-33003, -33003, 'tta');

    Note: The field type tta corresponds to the solr field type for text_type_ahead defined in your schema.xml.

  3. Add the query field and highlight field relationships to the configuration

    In order for the configuration to know which fields to query against and highlight against, you must add
    relationships between your configuration and your index fields. You can do this through the admin, or by sql:

    -- name hl field
INSERT INTO BLC_TYPE_AHEAD_HLT_FIELD (TYPE_AHEAD_HLT_FIELD_ID, TYPE_AHEAD_CONFIG_ID, INDEX_FIELD_TYPE_ID) VALUES (-33000, -33000, -33001);

-- mfg hl field
INSERT INTO BLC_TYPE_AHEAD_HLT_FIELD (TYPE_AHEAD_HLT_FIELD_ID, TYPE_AHEAD_CONFIG_ID, INDEX_FIELD_TYPE_ID) VALUES (-33001, -33000, -33002);

-- name query field
INSERT INTO BLC_TYPE_AHEAD_QUERY_FIELD (TYPE_AHEAD_QUERY_FIELD_ID, TYPE_AHEAD_CONFIG_ID, INDEX_FIELD_TYPE_ID, BOOST) VALUES (-33000, -33000, -33001, 10);

-- mfg query field
INSERT INTO BLC_TYPE_AHEAD_QUERY_FIELD (TYPE_AHEAD_QUERY_FIELD_ID, TYPE_AHEAD_CONFIG_ID, INDEX_FIELD_TYPE_ID, BOOST) VALUES (-33001, -33000, -33002, 3);

-- desc query field
INSERT INTO BLC_TYPE_AHEAD_QUERY_FIELD (TYPE_AHEAD_QUERY_FIELD_ID, TYPE_AHEAD_CONFIG_ID, INDEX_FIELD_TYPE_ID, BOOST) VALUES (-33002, -33000, -33003, 1);

  4. Add a new controller TypeAheadController to your site to process type ahead requests:

    @RestController
@RequestMapping("/type-ahead")
public class TypeAheadController extends com.broadleafcommerce.search.web.controller.TypeAheadController {

    @Override
    @RequestMapping(value = "/search", produces = "application/json")
    public List<TypeAheadSuggestion> typeAhead(HttpServletRequest request, HttpServletResponse response,
                                               @RequestParam(value = "q") String query,
                                               @RequestParam(value = "name", required = false) String name,
                                               @RequestParam(value = "contributor", required = false) Set<String> includedContributorKeys) {
        return super.typeAhead(request, response, query, name, includedContributorKeys);
    }
}

  5. All that is left to set up the frontend portion of the application. This typically entails creating html for
    displaying the type ahead results underneath the search box in the header, as well as javascript that is responsible for
    making the ajax to get new type ahead results when they user types characters. Here is an ajax call to get suggestions:

    BLC.ajax({
    type: 'GET',
    url: '/type-ahead/search',
    traditional: true, // so that the contributor request parameters are excluded array brackets
    data: {
       q: query,
       name: 'Demo Type Ahead',
       contributor: ['categories', 'keywords', 'manufacturers', 'products'],
       'contributor.products.limit': 5 // specify a custom limit for the product suggestions
    },
}, function(data) {
   // update page with type ahead results
});