Customize Suggest

As of version 4.0, all modification can be done from within the template files. We recommend that you create your own template as a copy of the existing template file advancedsuggest.phtml (to be found in app\design\frontend\base\default\template\factfinder\suggest) and then use the new template in app\design\frontend\{you_package}\{your_theme}\layout\factfinder\suggest.xml).

Customizing the JS file

The template file uses a JavaScript object FactfinderSuggest, which contains a method called loadDataCallback, that can be extended. The definition of the object can be found in the original which file is located under /js/factfinder/suggest.js and defined in the suggest.xml file.

So, if you want to change something in the JS file, follow the instructions:

• Copy suggest.xml to your theme
• Change

<action method="addJs"><script>factfinder/suggest.js</script></action>

to something like

<action method="addItem"><type>skin_js</type><script>js/factfinder/suggest.js</script></action>

• Copy js/factfinder/suggest.js to skin/frontend/your_package/your_theme/js/factfinder/suggest.js
• Make any changes you want.

What can potentially be changed

This and potentially the CSS are the only places you need to make changes to. The function is responsible for constructing the whole Suggest result from the JSON response delivered by the module. The downside is that you have to generate the Suggest result in code instead of just defining a few HTML templates. The upside, however, is that you can create pretty much anything within this function. The original advancedsuggest.phtml showcases the following capabilities:

• Using results from all FACT-Finder channels (primary and all secondary channels)
• Grouping by channel and inserting of headlines without compromising script.aculo.us's keyboard control
• Highlighting of different Suggest result types
• Inclusion of Suggest image thumbnails if available
• Display of hit counts if available
• Internationalization

A whole lot more can be thought of:

• Grouping by result types
• Display of any custom FACT-Finder Suggest attribute
• Abandoning the fixed list structure with <ol> and <li> and introducing <div>-elements (or any other HTML structure)
• ...and so on

However, there are a few things you need to pay attention to, when creating your own loadDataCallback for everything to go smoothly.

Firstly, about the callback function: The only parameter to the callback is an array of Objects. Each item represents one Suggest result and its properties correspond to the fields returned by FACT-Finder. In addition, if secondary channels are considered for Suggest, each item will also contain a property "channel" which contains the identifier of the channel it is from. The callback should return the whole HTML structure that goes into the autocompletion target as one string.

Secondly, about the HTML structure you create: For keyboard control to work, every suggest item (whatever element type it is) has to have the class selectable-item. You should also add an invisible element (style="display: none;) with both the selected and the selectable-item classes above all others, so that on displaying the result list, no element is pre-selected. Any item with a non-empty title tag will be clickable and the title will be used as the search term. Clicking on an item with an empty or without a title tag will not trigger the search. It does not matter which HTML elements you use to build your structure as long as they satisfy the above requirements for classes and title attributes.

Customizing styles (CSS)

The CSS file with the very basic styling can be found under the following path: /skin/frontend/base/default/css/factfinder_suggest.css. In case if you want to change the way the suggest results appear to the customer, just copy this file to your theme and let your imagination play with it.

Custom type definitions and translations

Types of suggestion results can be defined in FF backend and can have a specific identifier. By default, they are:

• ff_searchTerm
• ff_category
• ff_productName
• ff_brand

These keys are used for grouping results and also, after getting through the Magento translation tool, as titles for these groups. You can add any custom translation to them just by defining them in the locale file. For example, if you want that your groups were shown in German, you should add the corresponding CSV file to the de_DE locale directory so the full path to it would be app/locale/de_DE/FACTFinder_Suggest.csv (this is already included to the default module installation)