Cart frontend

Cart data

The browser’s local storage manages cart data. A one-time API call will be made to retrieve database entries for a session if the browser’s local storage is found empty. Upon receiving details those will be deleted from the existing database. All the information related to the session will be stored in local storage until the user clears it.

Upgrading to Funnelback DXP and local storage

Previous versions of the cart feature stored cart data and assets remotely.

With Funnelback DXP, cart data and assets are stored in the host browser’s local storage, as noted above.

When upgrading to Funnelback DXP, the first time a cart created using a previous version of the cart feature is opened, the data is moved to local storage.

This transfer is entirely transparent and requires no action on the part of either the end-user, or an administrator.

The only detectable difference between the previous, remote storage, and the current, local storage is perceived performance. Carts using local storage will, in many circumstances, update and perform faster than previously.

Caveats

The host browser’s local storage has limited capacity.
- It is usually 10 MB per client but this can vary from browser to browser.
- Also, the amount of local storage is customizable by browser end-users.
Because the browser’s local storage is used, data cannot be replicated on other devices or browsers with the same user ID. Each browser will have it’s independent storage.

Even when remote storage was used, data replication in this fashion was not (and is not) supported.
If a browser window or tab is opened in private or incognito mode, the session data is not retained when the private or incognito instance is closed.
Click history is recorded when a search result URL is clicked. If, however, the search result URL is opened in to a new browser tab or window, the click is not recorded.
- It takes end-user action (for example, right-clicking on a search result URL and then choosing Open Link in a New Tab or the equivalent contextual menu command) to open a search result URL in a new browser tab or window. Funnelback makes no effort to restrict the browser-based capabilities available to end-users, however, so such actions are always possible.
- Clearing click history will take effect on "Last visited time" only when page is refreshed.

Data model

Each item returned by GET API contains:

userId: ID of the user (Not applicable in case of local storage)
collection: collection to which result item belongs to
indexUrl: URL of result item that is used as unique identifier of that item
title: title of result item
summary: summary of result item
addedDate: date of adding item to cart in timestamp format
metaData: list of metadata

The cart widget is a JavaScript module that is loaded in the page in order to interact with and display cart data sourced from Funnelback.

Basic setup

In order to add the cart widget to your search website, you need to add some JavaScript code.

Note, you need to ensure that:

paths to the JavaScript files are correct
required libraries are included
the funnelback.session-cart.js code is included
widget is initiated by calling JavaScript class

<div id="search-cart"></div>

<script type="text/javascript" src="http://funnelback.server/s/resources-global/thirdparty/es6-promise-4.2.5/es6-promise.auto.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/thirdparty/handlebars-4.7/handlebars.min.js"></script>
<script type="text/javascript" src="http://funnelback.server/s/resources-global/js/funnelback.session-cart-1.0.0.min.js"></script>
<script type="text/javascript">
  var flbSessionCart = new Funnelback.SessionCart({
    apiBase: 'http://funnelback.server/',
    collection: '<collection_name>',
  });
</script>

Dependencies

The following third party code is used for this implementation:

Required

es6-promise - polyfill version of JS Promise (required by Internet Explorer, at least v4.2.5)
Handlebars - JS templating (at least v4.0.12)

Plugin parameters

Data settings

apiBase: The web service URL to fetch and update cart data.
collection: The collection for which the cart data should be fetched.

General display settings

iconPrefix: Define CSS class prefix used to display icons.

backIcon: Define icon to display within a link to return to search result page.
backLabel: Define text of a link to return to search result page.
clearClasses: Define CSS classes added to a button to clear all cart data.
clearIcon: Define icon to display within a button to clear all cart data.
clearLabel: Define text of a button to clear all cart data.
icon: Define icon to display within main header in cart widget.
label: Define text of main header in cart widget.
pageSelector: Define CSS selector to part of page to hide it when cart widget is displayed.
selector: Define CSS selector to element where content of cart should be displayed.

title: Define a CSS selector to an element with the search result title to extract its text to set it as a cart item title. CSS selector should be relative to its parent defined in item.list.
summary: Define a CSS selector to an element with the search result summary to extract its text to set it as a cart item summary. CSS selector should be relative to its parent defined in item.list.
metadataSelectors: Define a CSS selector to element item to extract its text to set as cart item metadata relative to its parent defined in item.list.

Cart count settings

icon: Define icon to display within cart widget trigger.
isLabel: If set to true display label within cart widget trigger, in other way display it as HTML title attribute.
label: Define a text to display within cart widget trigger.
selector: Define CSS selector to element which should trigger display of cart widget.
template: Define template used to display cart widget trigger.

Item trigger settings

iconAdd: Define icon to display within trigger to add an item to the cart.
iconDelete: Define icon to display within trigger to remove an item from the cart.
isLabel: If set to true display label within item trigger, in other way display it as HTML title attribute.
labelAdd: Define a text to display within trigger to add an item to the cart.
labelDelete: Define a text to display within trigger to remove an item from the cart.
position: Define relative position to selector element where trigger will be inserted.
selector: Define CSS selector of element where trigger will be inserted in relative position to it.
template: Define template used to display item trigger.

the itemTrigger settings can be configured independently for the results appearing within the search results and the cart results. See cartItemTrigger and resultItemTrigger for examples.

Plugin methods

addItem: Add new item to cart widget.
clear: Clear cart data for the current user.
deleteItem: Delete item from cart widget.
getOption: Get current settings of cart widget.
hide: Hide cart widget.
show: Show cart widget.
toggle: Toggle cart widget.

Adding cart HTML endpoint

The result cart can be processed and rendered by implementing a custom Groovy action, and a custom FreeMarker template. Typical use cases includes exporting the cart in a PDF or printable format, or contacting a third party web service to submit the cart information to it.

Processing the cart with a custom Groovy script

The cart will be processed by redirecting the user to /s/cart-process?collection=...&profile=.... When this URL is called, Funnelback will invoke the cart-process.groovy script from the collection configuration folder. This script needs to implement the following interface:

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.funnelback.publicui.search.model.collection.Collection;
import com.funnelback.publicui.search.model.transaction.session.CartResult;
import com.funnelback.publicui.search.model.transaction.session.SearchUser;
import com.funnelback.publicui.search.web.controllers.session.CustomCartProcessor;
import org.springframework.web.servlet.ModelAndView;
def class MyCartProcessor extends CustomCartProcessor {
  /**
   * Processes the cart
   *
   * @param collection Collection where processing takes place
   * @param user Current user from the session
   * @param cart Results cart, for the given collection and user
   * @return A {@link ModelAndView} containing the data and the view to use
   */
  @Override
  public ModelAndView process(Collection collection, SearchUser user, List<CartResult> cart) {
    ...
  }
}

The following parameters are passed in:

collection

A collection object, identical to the one used in User interface hook scripts

user

The current user, with its ID in user.id

cart

The cart content, as a list of results identical to the search data model results in transaction.response.resultPacket.resultsThe script must return a value of type ModelAndView. This is a composite class containing a data model and the name of a FreeMarker template to use to render the cart. For example, if you wanted to place the current date in the data model, and render the cart using the application-form.ftl template, you could use the following code:

def model = [:]
model["date"] = new Date()
return new ModelAndView("application-form", model);

Note that the Modern UI will automatically place the collection, current user and cart content in the data model, so you don’t need to add them by yourself.

Implementation of this Groovy script is optional. If it’s not present, the Modern UI will directly render the cart using the default FreeMarker template name: cart-process.ftl

Rendering the cart with FreeMarker

Once the cart has been processed, the configured FreeMarker template is called with the following entries in the data model: