Version 0.9 to 1.0 breaking changes and upgrade guidelines

This is for:

Developer

The JavaScript Search Framework version 1.0 was released to be bundled with the first release of the new Salesforce integration V2.

Feature wise, the June 2015 and July 31, 2016 JavaScript Search Framework version 0.9 and 1.0 releases are equivalent. While version 0.9 will be maintained for bug fixes to support existing deployments, new features are added only to version 1.0. You’re therefore encouraged to use, and if applicable, upgrade to version 1.0.

Coveo took advantages of the JavaScript Search Framework 1.0 release to refactor some aspects to start on cleaner grounds. The light breaking changes that come with this refactoring are described in this article for consideration when upgrading, to adjust previous JavaScript Search Framework version 0.9 deployments.

Changes summary

  • Namespace simplification

    Eliminated namespaces such as Coveo.Rest and Coveo.UI to rather expose all components and classes directly under the Coveo variable (see Namespace).

  • Template support

    Removed support for unused template engines. Added new HTML templates that are recommended to use rather than the still supported underscore templates (see Templates).

  • Component renaming

    Renamed a few components and/or some of their options to improve homogeneity (see Components).

    The FacetRange component is the only one with more changes (see FacetRange).

  • HTML refactoring

    Eliminated many default search page divisions and wrappers to simplify the layout (see Basic page layout and HTML markup).

  • CSS refactoring

    Renamed and created new CSS classes to significantly reduce rule nesting and simplify style customization (see CSS).

  • Font change

    Changed the default font from Arimo to Helvetica/Arial (see Fonts).

  • Supported browsers

    Changed the list of supported browsers (see Supported browsers).

Namespace

The Coveo JavaScript Search Framework version 0.9 exposed most of its components and classes under the following namespaces under the global Coveo variable:

  • Coveo.Rest

  • Coveo.Ui

  • Coveo.Events

  • Coveo.Controllers

  • Coveo.Models

In version 1.0, all those namespaces are eliminated and all classes are exposed directly under the Coveo variable.

Upgrade guideline

In your code editor, perform a case-sensitive replace in all files that include JavaScript Search Framework code:

  • Replace Coveo.Rest, Coveo.Ui, Coveo.Events, Coveo.Controllers, and Coveo.Models

  • With Coveo

Common namespace migrations:

Version 0.9 Version 1.0

Coveo.Rest.SearchEndpoint

Coveo.SearchEndpoint

Coveo.Ui.QueryController

Coveo.QueryController

Coveo.Ui.QueryBuilder

Coveo.QueryBuilder

Templates

In the JavaScript Search Framework version 0.9, the development led to explore and include different ways to allow you to customize search result templates.

Version 1.0 introduces HTML templates, which are recommended for their ease of use and flexibility, but also supports Underscore templates.

Note

Upgrade guideline

  • If you were using Underscore templates for your version 0.9 search results, they will work transparently in version 1.0.

  • Instead, consider redefining your search results with HTML templates using the Interface Editor.

  • If you were using other version 0.9 template types (JsRender, Handlebars, or JSON), you must upgrade your search result templates, preferably to HTML templates.

HTML templates

HTML templates are a new addition to version 1.0. They allow you to easily customize search result templates using the Interface Editor. HTML templates are structured using configurable rows and cells into which you can drag search result components. Coveo now recommends that you use HTML templates because they offer the best compromise between ease of use and flexibility.

In your search page, the HTML templates generated by the Interface Editor look like the following code snippet:

<div class="CoveoResultList">
    <script id="MyTemplate" class="result-template" type="text/html" data-condition="raw.somefield=="MyValue"" >
        <div class="coveo-result-frame">
            <div class="coveo-result-row">
                <div class="coveo-result-cell>
                    [... content of the first template ...]
                </div>
            </div>
        </div>
    </script>
</div>

Underscore templates

While the JavaScript Search Framework version 0.9 supported other template engines, most people chose to use Underscore templates. These templates are very powerful, but because they’re arbitrary JavaScript functions, they’re not a good candidate to be made customizable with the Interface Editor.

Version 1.0 fully supports Underscore templates, but they’re not customizable with the Interface Editor.

In your version 1.0 search page, the Underscore templates look like the following code snippet:

<div class="CoveoResultList">
    <script class='result-template' id='Template1' data-condition='raw.somefield=="MyValue"' type='text/underscore'>
        [... content of the first template ...]
    </script>

    <script class='result-template' id='Template2' data-condition='raw.somefield=="MyValue"' type='text/underscore'>
        [... content of the second template ...]
    </script>
</div>

Other template types

In the JavaScript Search Framework version 1.0, the following search results template types are deprecated and won’t work:

  • JsRender templates

  • Handlebars templates

  • JSON templates.

Components

Most of the changes relative to the components are component and/or option name changes, often only correcting capitalization. The tables in the sub-sections list all changes.

Note

Upgrade guideline

In your favorite code editor, use a case sensitive REGEX to find all and replace all occurrences of the old component or option names listed in the sub-section tables in all your files that include JavaScript Search Framework code.

OmniBox - Omnibox

The changes only involve changing the casing of B in onmiBox to lowercase.

Change Version 0.9 Version 1.0
Component name

OmniBox

Omnibox
CSS class name CoveoOmniBox CoveoOmnibox
Option name omniBoxDelay New option name: omniboxDelay
Option name omniBoxTimeout New option name: omniboxTimeout
Option name omniBoxChangeLimit New option name: omniboxChangeLimit
Option name omniBoxMinimumLetters New option name: omniboxMinimumLetters
Event populateOmniBox populateOmnibox

SearchInterface

Change Version 0.9

Version 1.0
Option name Old option name: hiddenExpression New option name: expression
HTML markup option name

Old option name when set through the HTML markup: data-hidden-expression

Note: Was the markup name for the hiddenExpression option.

New option name: data-expression

Note: Is the markup name for the expression option.

The changes only involve changing the casing of B in SearchBox to lowercase.

Change Version 0.9

Version 1.0
Component name

SearchBox

Searchbox
CSS class name CoveoSearchBox CoveoSearchbox
Option name Old option name: activateOmniBox

New option name: enableOmnibox
HTML markup option name

Old option name: data-activate-omnibox

New option name: data-enable-omnibox

QueryBox - Querybox

The changes only involve changing the casing of B in QueryBox to lowercase.

Change Version 0.9

Version 1.0
Component name

QueryBox

The component is now named Querybox
CSS class name CoveoQueryBox CoveoQuerybox

Option name

Default value

Old option name: disableQuerySyntax

false

New option name: enableQuerySyntax

true

HTML markup option name

Default value

Old option name: data-disable-query-syntax

false

New option name: data-enable-query-syntax

true

Pager

Change Version 0.9

Version 1.0
Option name Old option name: navigationButton New option name: enableNavigationButton
HTML markup option name

Old option name when set through the HTML markup: data-show-previous-next

Note: Was the markup name for the navigationButton option.

New option name: data-enable-navigation-button

Note: Is the markup name for the enableNavigationButton option.

ErrorReport

Change Version 0.9

Version 1.0
Option name Old option name: popUp New option name: enablePopup

Facet

Change Version 0.9

Version 1.0
Option name Old option name: uniqueId

New option name: id
Option name Old option name: allowTogglingOperator New option name: enableTogglingOperator

QuickView - Quickview

The changes mainly involve changing the casing of V in QuickView to lowercase.

Change Version 0.9

Version 1.0
Component name

QuickView

Quickview
CSS class name CoveoQuickView CoveoQuickview
Option name

Old option name: showLoadingAnimation

New option name: enableLoadingAnimation

In version 0.9, you could specify the content of the Quickview as follows:

Version 0.9 Quickview markup

<script class='result-template' type='text/underscore'>
    <div>

        [... other components ...]

        <div class='CoveoQuickView'>
            [... custom content to be displayed when the user opens the quickview ...]
        </div>

    </div>
</script>

-- OR LIKE THIS ---

<script class='result-template' type='text/underscore'>
    <div>

        [... other components ...]

        <div class='CoveoQuickView' data-template-id='MyCustomTemplate'></div>

    </div>
</script>

<script class='result-template' id='MyCustomTemplate' type='text/underscore'>
    [... custom content to be displayed when the user open the quickview ...]
</script>

The problem with the first approach was that it was impossible to customize the actual content and appearance of the icon in the result list itself, only the content.

In version 1.0, you can customize a Quickview as follows:

Version 1.0 Quickview markup

<script class='result-template' type='text/underscore'>
    <div>

        [... other components ...]

        <div class='CoveoQuickview' data-template-id='MyCustomTemplate'>
            [... what will appear in your result list and can be clicked to open the actual Quickview content ...]
            [... this is optional, if you put nothing here, then the default appearance of the quickview button will be used ...]
        </div>

    </div>
</script>

<script class='result-template' id='MyCustomTemplate' type='text/underscore'>
    [... custom content to be displayed when the user opens the quickview ...]
</script>

QuickViewDocument - QuickviewDocument

The changes only involve changing the casing of V in QuickView to lowercase.

Change Version 0.9

Version 1.0
Component name

The component was named QuickViewDocument

The component is now named QuickviewDocument
CSS class name CoveoQuickViewDocument CoveoQuickviewDocument

ResultList

Change Version 0.9

Version 1.0
Option name

Old option name: showInfiniteScrollWaitingAnimation

New option name: enableInfiniteScrollWaitingAnimation

ResultsPreference

Change Version 0.9

Version 1.0
Option name

Old option name: showOpenInOutlook

New option name: enableOpenInOutlook

Tab

Change Version 0.9

Version 1.0
Option name

Old option name: uniqueId

New option name: id

TopAnalyticsSuggestions - AnalyticsSuggestions

The changes only involve removing the Top prefix.

Change Version 0.9

Version 1.0
Component name

The component was named TopAnalyticsSuggestions

The component is now named AnalyticsSuggestions
CSS class name CoveoTopAnalyticsSuggestions CoveoAnalyticsSuggestions

TopFieldSuggestions - FieldSuggestions

Change Version 0.9

Version 1.0
Component name

The component was named TopFieldSuggestions

The component is now named FieldSuggestions
CSS class name CoveoTopFieldSuggestions CoveoFieldSuggestions

FacetRange

In both version 0.9 and 1.0 the FacetRange component still:

  • Can be used to create a "classic" facet with values expressed as ranges.

  • Inherits from the Facet Component and provides the same base options.

The changes are related to the slider and graph options:

Change Version 0.9

Version 1.0
Slider and graph related options Available

Deprecated on FacetRange Component, but all available on the new FacetSlider Component.
Note

Upgrade guideline

If you used the version 0.9 FacetRange Component to create a facet with a slider and graphical display of values, rather use the new FacetSlider Component for this facet.

Style and layout

Basic page layout and HTML markup

The default search page layout was reworked to make it simpler, by removing many divisions and wrappers that are now obsolete in version 1.0.

The following code sample presents the new version 1.0 default search page layout (where you replace the tag with the actual components that you want to include in your search page):

Default search page 1.0

<[[tag]] id="search" class="CoveoSearchInterface">       <!-- Replace [[tag]] with either a div or the body of the page itself -->
[[foldings]]                                            <!-- Insert one or more Folding components if necessary. -->
<div class="CoveoAnalytics"></div>
<div class="coveo-tab-section">
  [[tabs]]                                              <!-- Insert one or more Tab components if necessary -->
</div>

<div class="coveo-main-section">
    <div class="coveo-facet-column">
        <div class="coveo-logo"></div>
        [[facets]]                                      <!-- Insert one or more Facet components if necessary -->
    </div>
    <div class="coveo-results-column">
        <div class="CoveoSettings" data-include-in-menu=".CoveoShareQuery,.CoveoPreferencesPanel"></div>
        <div class="CoveoSearchbox"></div>
        <div class="CoveoShareQuery"></div>
        <div class="CoveoPreferencesPanel">
            <div class="CoveoResultsPreferences"></div>
            <div class="CoveoResultsFiltersPreferences"></div>
        </div>
        <div class="CoveoBreadcrumb"></div>
        <div class="coveo-results-header">
            <div class="coveo-summary-section">
                <span class="CoveoQuerySummary"></span>
                <span class="CoveoQueryDuration"></span>
            </div>
            <div class="coveo-sort-section">
                [[sorts]]                               <!-- Insert one or more Sort components if necessary -->
            </div>
        </div>
        <div class="CoveoHiddenQuery"></div>
        <div class="CoveoDidYouMean"></div>
        <div class="CoveoErrorReport"></div>
        <div class="CoveoResultList">
            [[templates]]                               <!-- Insert one or more template scripts if necessary -->
        </div>
        <div class="CoveoPager"></div>
    </div>
</div>
</[[tag]]>
Note

Upgrade guideline

  • You can upgrade and see where the original search page layout and HTML markup brakes in your search page and then, look in your browser console to fix one problem at a time.

  • A better practice is to restart your search page layout from scratch using one of the .html files supplied with the package.

CSS

The JavaScript Search Framework version 0.9 relied on deep nesting of CSS classes to ensure specificity. Deep nesting however often made style customization more complex, for example sometimes requiring to use the !Important rule to ensure that the desired result.

Version 1.0 rather relies on longer CSS class names and reduced nesting between dependent rules to simplify style customization for future deployments.

Many version 0.9 CSS classes are renamed in version 1.0. The list of renamed CSS classes is too long to be explicitly listed.

Note

Upgrade guideline

  • You can upgrade and see what CSS customization breaks in your search page and then, fix one problem at a time.

  • A better practice is to restart your CSS customization from scratch to avoid carrying customization for old CSS classes.

  • Take special care for the following components: Facet Component, Breadcrumb Component, Omnibox Component, Pager Component.

Fonts

The default font changed from Arimo to the standard Helvetica/Arial, and eliminate the need to distribute font files.

Change Version 0.9

Version 1.0
Default font Arimo Helvetica, Arial
Font file distribution in package .woff included None included
Note

Upgrade Guidelines

  • Ensure to get rid of the old Arimo .woff fonts folder.

  • Customize the fonts if desired and provide font files when appropriate.

Supported browsers

The list of supported browser versions changed for both the search interfaces and the Interface Editor. The version 1.0 supports new browser versions and no longer support versions that were deprecated by the software publishers (see Browser Support).

Changed browser support Version 0.9

Version 1.0
Microsoft Edge Not Supported Supported

The mobile version support:

Changed mobile operating system support Version 0.9

Version 1.0
iOS 7 and 8 Supported Not supported

iOS 8.x and 9.x

 Not Supported Supported
Android 5.x Not Supported Supported