Version 0.9 to 1.0 breaking changes and upgrade guidelines

Version 0.9 to 1.0 breaking changes and upgrade guidelines

This is for:

Developer

The JavaScript Search Framework version 1.0 was released (see July 2015 release (v1.0.20)) to be bundled with the first release of the new Salesforce integration V2 (see July 2015 release: v2.3).

Feature wise, the JavaScript Search Framework version 0.9 and 1.0 June 2015 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 that you need to consider 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.

var endpoint = new
Coveo.Rest.SearchEndpoint();

var endpoint = new
Coveo.SearchEndpoint();

var builder = new
Coveo.Ui.QueryBuilder();

ar builder = new
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.

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 and drop 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.

OmniBox - Omnibox

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

SearchInterface

SearchBox - Searchbox

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

QueryBox - Querybox

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

Pager

ErrorReport

Facet

QuickView - Quickview

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

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

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

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

ResultList

ResultsPreference

Tab

TopAnalyticsSuggestions - AnalyticsSuggestions

The changes only involve removing the Top prefix.

TopFieldSuggestions - FieldSuggestions

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:

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 [[SomeComponent]] tag with the actual component(s) that you want to include in your search page):

<[[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]]>

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.

Fonts

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

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

The mobile version support:

Is this article useful?

You can close this window or leave a comment below.

Very useful Not really

Can you tell us more about your experience today?

Comments (optional)

Need help with our product? Please open a support case for expert assistance. Use this feedback option to comment on the article only.

Submit

Is this article useful?

You can close this window or leave a comment below.

Very useful Not really

Can you tell us more about your experience today?

Comments (optional)

Need help with our product? Please open a support case for expert assistance. Use this feedback option to comment on the article only.

Submit