Help Center

Menu

Auto-completion CSV file format

Introduction

This guide describes how to use a custom CSV data file as a source for auto completion suggestions, allowing you to display complex suggestions and trigger complex actions when a suggestion is selected.

CSV Location

The CSV file should be named auto-completion.csv, and can be created via the results page Configuration file manager or via WebDAV.

This file will be read and processed at indexing time.

CSV format

Each line of this CSV file will correspond to a suggestion. Each line must have 8 columns, though some columns may be empty.

Example

Completion Text,70,This is plain text,T,Display samples,1,plain text,Q
Completion JSON,80,{\"key1\":\"value1\"\,\"key2\":\"value2\"},J,Display samples,1,Json,Q
Completion HTML,90,"<div class=\"sugg\">This <b>actually</b> is <p><span style=\"color: red\">HTML</span></div>",H,Display samples,1,v:html,Q
Completion Callback,1,'Callback. Current document title is: <i>'+document.title+'</i>.';,C,Display samples,1,Javascript,Q
Action Query,1,This will run a query,T,Action samples,1,`a query`,Q
Action URL,90,This will open an URL,T,Action samples,1,http://test-data.funnelback.com/,U
Action Callback,80,This will call a JS callback,T,Action samples,1,jQuery('img').attr('src'\,,'images/pdf_large.gif');jQuery('#fb-matching').fadeOut(1500);,C
Action Extend,100,This will add a category to the query,H,Restrict to category: ,,s:Category,E

Columns description

Column 1 - key

Type: String (case insensitive)

Contains the text against which the partial query entered by the user is matched against.

For example if this column contains "Australia", this suggestion will trigger if a user enters "aus".

Column 2 - weight

Type: Number (floating point, range 0-999)

Used to rank suggestions which matches the partial query, in case multiple suggestion matches a given partial query.

If the partial query is "do", both "dog" and "donut" will be returned. The one with the higher weight will be returned first (assuming the auto-completion sort option is set to sort by score).

Column 3 - display

Type: String (Text, HTML, Javascript, JSON)

This is what will be displayed to the user for this suggestion. It can be:

  • Plain text: Will be displayed with any special HTML characters escaped,

  • JSON data: Can be templated at presentation time,

  • Javascript: The JS statement will be evaluated, and its return value displayed (as HTML, not escaped),

  • HTML fragment (deprecated): Will be displayed as formatted HTML. The JSON data display type should be used in preference to HTML fragment as the structured data is maintained in the response. The Concierge widget includes configuration to define how the fielded values should be templated.

Please also note the standard escaping rules for CSV files.

Special characters like double quotes, backslashes or commas can be escaped using a backslash (\\ , \" , \,)

  • If this column is entirely double-quoted it will be returned as is, meaning that any escaped character will be preserved escaped,

  • If this column is not double-quoted backslashes will be removed from the output.

  • To display an HTML fragment, use double-quoted strings and backslashes: "HTML fragment"

  • To use a Javascript callback simply set the function call: myJavascriptCallback();.

  • To output JSON data, use an unquoted string and backslashes: { \"Name\" : \"Bob\" \, \"Age\" : \"25\" }

Column 4 - display type

Type: Single capital letter: C,H,J or T

Indicates the type of the previous display column:

  • C for Javascript Callback,

  • H for HTML,

  • J for JSON data,

  • T for plain Text.

Column 5 - category

Type: String

The category of the suggestion. This field allows to classify suggestion in multiple categories.

If the suggestion concerns a product, you could use "Product" here. All the suggestions with the same category will be displayed under the same category header in the search result page.

Column 6 - category type

Type: Single character, unused for now

Reserved for future use.

Column 7 - action

Type: String (Text, Javascript, URL, query specified using the Funnelback query language)

Action that will be performed when the user selects this suggestion. It can be:

  • Plain text: The text will replace (query action) or add to (extend action) the query field,

  • Javascript: The javascript statement will get executed. To execute a Javascript statement simply set the Javascript code to be executed e.g. document.getElementById('discount').value='50';

  • URL: The user will get redirected to this URL. The URL should be set to the absolute URL string. e.g. http://www.example.com/

  • Query: To run a specific query, use for example a:Shakespeare (search for Shakespeare in the a metadata field). The query must be specified using the Funnelback query language.

Column 8 - action type

Type: Single capital letter: C, Q, U, E or S

Indicates the type of the previous ''action'' column:

  • C for a Javascript Callback,

  • U for opening an URL,

  • Q for running a Query,

  • E for Extending a query,

  • S for System generated auto completion and should not be used.

Mandatory columns

Only the key and weight values are mandatory.

  • If display and display type are empty, the default behavior is to display the key as the suggestion.

  • If action and action type are empty, the default behavior is to submit a query using the key as query term.

Use cases

Displaying JSON data using a template

When the display type column is set to J, the value of the display column will be returned as JSON data. This JSON data can be processed using a Handlebars templating tool and auto-completion widget parameter "template", allowing to separate the suggested data (embedded in the CSV file) and the way it’s displayed.

For example, if you want to embed product prices as JSON data you could use the following CSV file:

Donut,1,{\"Name\":\"Donut\" \, \"Price\": 3 \, \"sku\": \"AV432\" },J,,,,
Cheesecake,1,{\"Name\":\"Cheesecake\" \, \"Price\": 3.5 \, \"sku\": \"HS184\" },J,,,,
Orange,1,{\"Name\":\"Orange\" \, \"Price\": 2 \, \"sku\": \"GW112\" },J,,,,
Cherry,1,{\"Name\":\"Cherry\" \, \"Price\": 2.3 \, \"sku\": \"IE869\" },J,,,,

Then, in your template file, add the following scriptlet:

<script id="flb-completion-tmpl" type="text/x-handlebars-template">
   <span class="name">{{label.Name}}</span>
   <span class="price">$ {{label.Price}}</span>
   <img src="/product-images/by-sku/{{label.sku}}.png" />
</script>

<script>
jQuery('input.query').autocompletion({
  datasets: {
   products: {
    collection: 'products',
    profile : 'auto-completion',
    show: 10,
    template: {
      suggestion: $('#flb-completion-tmpl').text(),
    },
   }
  },
  length: 3
 });
</script>

With this setup each suggestion will be displayed as an HTML fragment with the {{…​}} tags filled with values from the JSON data. If you wish to change the way suggestions are displayed you may change the template without modifying the CSV data or re-indexing the collection.

Displaying HTML fragments with images

Using HTML fragment allows rich suggestions to be displayed. For example, if you want to suggest different products with their price and a thumbnail image, classified in various categories, you could use the following CSV file:

Donut,1,"<p><img src=\"donut.png\" /><b>Donut</b> - <i>$3</i>",H,Sweets,1,,
Cheesecake,1,"<img src=\"cheesecake.png\" /><b>Cheesecake</b> - <i>$3.50</i>",H,Sweets,1,,
Orange,1,"<img src=\"orange.png\" /><b>Orange</b> - <i>$2</i>",H,Fruits,1,,
Cherry,1,"<img src=\"cherry.png\" /><b>Cherry</b> - <i>$2.30</i>",H,Fruits,1,,
This method is not recommended. Please use instead JSON data and templating tool.

Using a Javascript display callback

When the Display type column is set to C, the value of the display column is evaluated as a Javascript call, and its return get displayed as a suggestion.

For example, to suggest company names and display their stock price, and to navigate to the web site of the company when the user selects a suggestion, you could use the following CSV file:

Donut Company Pty Ltd,1,fetchStockPrice('DON');,C,,,http://www.donutcorp.com/,U
CheeseCake Inc.,1,fetchStockPrice('CHK');,C,,,http://www.cheesecake.com/,U

and the following Javascript function:

function fetchStockPrice(symbol) {
   // Fetch stock market data
   var data = remoteServiceCall(symbol);
   ...

   return data.companyName + ' (' + symbol + ') $' + data.currentPrice + ' (Higher: ' + data.hiPrice + ')';
}

Using a Javascript action callback

When the Action type column is set to C, the value of the action column is evaluated as a Javascript call when the user selects the suggestion.

For example, if you want to refresh the stock market information displayed elsewhere on the search result page when a user selects a suggested company, you could use the following CSV file:

Donut Company Pty Ltd,1,,,,,refreshData('DON'),C
CheeseCake Inc.,1,,,,,refreshData('CHK'),C

and the following Javascript function:

function refreshData(symbol) {
   // Fetch stock market data
   var data = remoteServiceCall(symbol);
   ...

   document.getElementById('price_info').value = data.currentPrice;
   if (data.currentPrice > data.lastWeekPrice) {
      document.getElementById('status').src = 'green.png';
   }
}

See also