FAQ content

Add or edit a custom search source

In this article

The Custom source type allows you to create search sources for third-party services. For example, you could create a search source for your library catalog, your discovery layer, or a specific database. That would allow you to include results from those systems right alongside your LibApps search sources.

Custom search source requirements

Because each third-party system will have its own requirements for retrieving data, setting up a custom search source will require some setup on your end. In a nutshell, you will need to create and host a script that acts as an intermediary between LibApps and the third-party system, such as your catalog or a database. This will ensure that you're making a request to the third-party system using that vendor's required format (via their API, for example) and authentication method, and sending the retrieved data to LibApps using our expected format.

In a nutshell, here's how this works:

  1. You create a hosted script that can receive the search query from LibApps, send a corresponding request to the third-party system, and pass the retrieved data back to LibApps in the correct format.
    • For details on how to retrieve data from your third-party system, please consult that vendor's API or related documentation.
  2. You create a new custom search source in LibApps, with the URL of your custom script as the Request URL.
  3. When a user performs a search, we'll make an AJAX JSONP request to that URL, sending along the query and any other data you provide (Field Name/Key and Field Value).
  4. Your script receives the request from LibApps, then sends a corresponding request to the third-party system using the format and authentication method defined by the vendor.
  5. The third-party system sends the data back to your script.
  6. Your script converts the data into a properly formatted JSONP object and passes it to LibApps.
  7. We display the search results using the Results Rendering format you specify.

The following sections provide more info on creating and configuring your custom search source, including the required data formats.

Configuring the search source

  1. From the LibApps dashboard, go to Admin > Search Sources.
  2. Click the  Add Search Source button or click the Edit Source () icon in the Actions column to configure an existing search source.

configuring a custom search source step 1

  1. On the Add/Edit Search Source page, configure general settings for the custom search source. Including:
    1. Name: appears on the search results page. For the Tabbed search, it's the name of the tab. For the Bento search, it's the name of the box.
    2. Description (optional): appears above the search results.
  2. Set up the Request Parameters. Here you'll tell specify where to send the search query and provide any additional data that should be sent. The optional Field Name/Key and Value pairs will be added to the Request URL that is sent to the vendor's API.
    1. Request URL: the URL to which LibApps will send the search requests.
    2. Field Name / Key 1 & Field Value 1: (Optional) These are additional pieces of information to send along with the request. You can add as many Name/Key and Value pairs as you want. When the search is submitted by the user, a request is sent to the Request URL. See the example JSONP request below for more details.
  3. In the Results Rendering section, define what to do with the data once the vendor's API returns it.
    1. Item Template (Required): The Item Template tells the search results page how to render the results using a Mustache-like format. The default template loads automatically, so you have something to work with as an initial example. The template is inserted into an LI element in the results UL. Both jQuery and UnderscoreJS are available for use in the templates. See the item template overview below for examples.
    2. Item Callback: This is an optional field - it's a callback on each LI element in the results after they're added to the DOM. "this" in the callback is bound to the LI element.
    3. Full Search URL: This is also an optional field, but probably a good idea to fill it out. This is where the "View More Results" link (at the bottom of all search results) brings folks when they click it. For example, for the AZ Search Source, it brings folks to the Databases A-Z page in that LibGuides site, with the search executed.
  4. Click Save.

configuring a custom search source step 2

Example JSONP request

Here is an example of a JSONP request sent to a custom search source:


In this request, you'll find the following parameters:

  • {String} callback: used for jsonp formatting, it should be passed back in the response.
  • {String} q: the query string.
  • {Number} page: the request page number.
  • {Numbers} perpage: the number of results to return
  • {String} sort: requested sorting in the form of FIELD_DIRECTION (i.e., 'date_asc', 'title_desc'); if no sort is set, it will be '_'.

Response data example

At this point, the vendor processes the search request and sends results back to LibApps. These results must be in JSONP format. Here's an example:

callback123456( '{"total_results":103,"perpage":20,"sort":
{"field":"title","dir":"asc"},"sort_options":[{"field":"title","dir":"asc","label":"Title A-Z"},
{"field":"relevancy","dir":"asc","label":"Most Relevant"}],"results":
[{"title":"Walden","author":"Thoreau, Henry David","url":"http://catalog.com/12345"},{"title":"Walden & Civil 
Disobediance","author":"Thoreau, Henry David","url":"http://catalog.com/56789"},
{"title":"Walden: or, Life in the Wood","author":"Thoreau, Henry David","url":"http://catalog.com/01278923"}]}');

The following is an overview of what LibApps will look for in the response data:

  • {String} callback: Name of the callback passed in the request
  • {Number} total_results: Total results found for the query
  • {Number} perpage: How many results returned per page
  • {Object} sort: Current sort of the returned results
  • {String} sort.field: Field the results are sorted on
  • {String} sort.dir: Whether the sort is ascending or descending
  • {Array} sort_options: Available sorting options for the results
    • {Object} sort_options[]
    • {String} sort_options[].field: Field(s) results can be sorted on
    • {String} sort_options[].dir: Direction(s) results can be sorted on
    • {String} sort_options[].label: How the option will display in the interface
  • {Array} results: Result objects
    • If using the default item template, you must pass at least:
      • {String} url: Result URL
      • {String} title: Result title (preferably as plain text)
    • Otherwise this object will be used to populate your item template, so any variables in the template should be found in the object.

Item template overview

Here's the basic idea of how to construct a template & some examples

  • Display a field: {{fieldname}}
  • Display a field, escaping HTML: {{{fieldname}}}
  • Use JavaScript: {{# JavaScript }}

Default Template

<a href="{{url}}">{{title}}</a>

Simple Example

<div class=s-srch-result-title>
   <a href="{{url}}">{{question}}</a>
<div class="s-srch-result-meta">
   Updated: {{updated}}

Complicated Example (using LibAnswers as an example)

<div class=s-srch-result-title>
   <a href="{{url}}" data-faqid={{id}}>{{question}}</a>
<div class="s-srch-result-meta">
   <span class="s-srch-result-date"><span class=metalabel>Updated</span> {{updated}}</span>
   {{# if (topics.length > 0) { }}
      <span class="divider">|</span>
      <span class="s-srch-result-subj">
         <span class=metalabel>Topics</span>
         <ul class="list-inline metavalue" aria-label="Topics">
            {{# _.each(topics, function(v,k){ }}
                  {{# if (k+1 < topics.length){ print(\';\'); } }}
            {{# }); }}
   {{# } }}