Templates Reference

Templates are the basic building blocks of Instant Answer displays. Below is a detailed reference of the properties and usage of each.

To understand the context of templates and how they fit into your Instant Answer, start with the Templates Overview.

Important Note

Before using these templates please familiarize yourself with the Instant Answer display options (for example, Spice or Goodie) document to understand the proper usage of both the templates block and the options block. Understanding these is crucial to implementing templates properly and effectively.

You will be specifying these templates indirectly - as part of a Template Group. The Templates Groups Overview will help you think about the big picture of which template groups best fit your Instant Answer.

Templates

The list of built-in templates includes:

text_item Template

Template for displaying textual information tiles, each with an optional icon.

Template Diagram

text_item template 

+------------------+
icon
title, altSubtitle
subtitle
description
footer
            dateBadge
+------------------+

Available Features

  • icon [optional] string url

    URL path to icon image

  • url [optional] string url

  • title [required] string url
  • altSubtitle [optional] string or string array
  • subtitle [optional] string or string array
  • description [required] string
  • footer [optional] sub-template

  • dateBadge [optional] object

    An object with either a text string property or a month and day string properties. For an example of this property in action, search for "concert in toronto" and see the SeatGeek Events by City Spice.

Example Usage

Template Groups

text_detail Template

A template for displaying textual information detail, with no image or icon.

Template Diagram

text_detail template

+-------------------------------------+

title_content or title
subtitle_content or subtitle
content

+-------------------------------------+

Available Features

  • title_content [optional] sub-template

  • title [optional] string

    Available only if title_content is not specified

  • subtitle_content [optional] sub-template

  • subtitle [optional] string or string array

    Available only if subtitle_content is not specified

  • content [optional] sub-template

Example Usage

Template Groups

basic_image_item Template

A tile template where images are the main feature, accompanied by text.

Template Diagram

basic_image_item template

+------------------+
image
title
description
rating
ratingText
+------------------+

Available Features

  • url [optional] string url

  • image [required] string url

    URL path to image

  • title [required] string

  • description [optional] string

    Limited to 56 characters, truncated to whole words with an ellipsis

  • rating [optional] float

    A positive float with one decimal point, up to 5.0

  • ratingText [optional] string

Example Usage

Template Groups

products_item Template

A tile item template where images are emphasized, with features suited for items that can be purchased.

Template Diagram

products_item template

+------------------+
img
title
price
brand
rating
+------------------+

Available Features

  • url [optional] string url
  • img [required] string url
  • title [required] string
  • price [optional] string
  • brand [optional] string

  • rating [optional] float

    A positive float with one decimal point, up to 5.0

  • reviewCount [optional] integer

    The count of reviews Automatically formatted to include comma thousands separators

  • url_review [optional] string

    URL path to reviews

Example Usage

Template Groups

products_detail Template

A detail template where image is emphasized, suited to feature for an item that can be purchased.

Template Diagram

products_detail template

+------------------------------------+
                heading
                rating, reviewCount
                price, brand
    img         subtitle_content                
                abstract
                buy
+------------------------------------+

Available Features

  • img [optional] string url

    URL path to image

  • url [required] string url

  • heading[required] string

  • rating [optional] float

    A positive float with one decimal point, up to 5.0

  • reviewCount [optional] integer

    The count of reviews Automatically formatted to include comma thousands separators

  • price [optional] string

  • brand [optional] string
  • subtitle_content [optional] sub-template

  • abstract [required] string

    Limited to 400 characters, truncated to whole words with an ellipsis

  • buy [optional] sub-template

    Can be used to provide a call-to-action, such as a button.

Example Usage

Template Groups

products_item_detail Template

A template for drilling-down into a particular item on the same page. Emphasizes an image, and suited to feature for an item that can be purchased. This template features an optional call-to-action.

Template Diagram

products_item_detail template

+------------------------------------+
                heading
                price, brand
    img_m       subtitle_content
                rating, reviewCount
                abstract
                buy
+------------------------------------+

Available Features

  • img_m [optional] string url

    URL path to image

  • heading [required] string

  • url [required] string url
  • price [optional] string
  • brand [optional] string
  • subtitle_content [optional] sub-template

  • rating [optional] float

    A positive float with one decimal point, up to 5.0

  • reviewCount [optional] integer

    The count of reviews Automatically formatted to include comma thousands separators

  • url_review [optional] string url

    Link to source reviews page

  • abstract [required] string

  • buy [optional] sub-template

    Can be used to provide a call-to-action, such as a button.

Example Usage

Template Groups

basic_icon_detail Template

A template for displaying textual information detail, with a small image, icon, or character badge.

Template Diagram

+------------------------------------------------+
image and/or badge      title
                        subtitle
                        altSubtitle

                        content *or* description                        

+------------------------------------------------+

Available Features

  • image [optional] string url

    URL path to image

  • badge [optional] string

  • title [optional] string
  • subtitle [optional] string or string array
  • altSubtitle [optional] string or string array
  • content [optional] sub-template

  • description [conditional on content] string

    Available and required if content not specified

Example Usage

None - yet

Template Groups

basic_info_detail Template

A detail template which shows in-depth information. This template includes an auxiliary area for listing properties.

Template Diagram

basic_info_detail template

The same template, with the aux feature:

basic_info_detail_w_aux template

+-------------------------------------------------------+
                title
    image       subtitle                        
                content or description          infoboxData
+-------------------------------------------------------+

Available Features

  • url [required] string url

  • image [optional] string url

    URL path to image

  • title [optional] string

  • subtitle [optional] string or string array

    Available only if title specified

  • content [optional] sub-template

  • description [conditional on content] string

    Available and required if content not specified

  • infoboxData [optional] array

    An array of objects used to render an InfoBox

Example Usage

Template Groups

The Infobox

In the basic_info_detail template, the InfoBox floats on the right side of the AnswerBar. It presents detailed information in a table of key-value pairs:

infobox

To display the InfoBox in the basic_info_detail template, an item must have an infoboxData property specified. This is an array of objects, each with the following properties:

  • label [required] string

  • url [optional] string url

    Used to turn label element into a link

  • value [optional] string or array

    Use array to display nested properties)

The first object in the array can also be used solely to specify a heading for the InfoBox. This object would contain only one property:

  • heading [optional] string

    Specified in its own separate object, first in the array

For example, when "mtg nullify" is searched, mtg.js dynamically generates the following array for infoboxData:

[
    {
        heading: "Card Details"
    },
    {
        label: "Mana Cost",
        value: "UU"
    },
    {
        label: "Converted Mana Cost",
        value: 2
    },
    ...
]

This data shows up in the AnswerBar, to the right:

mtg infobox

It is also possible to specify labels alone, with or without urls. This is the infoboxData value generated by urban_dictionary.js when searching for "urban dictionary cool":

[
    {
        heading: "Related Terms:"
    },
    {
        label: "Awesome",
        url: "https://duckduckgo.com/?q=ud+awesome&ia=dictionary"
    },
    {
        label: "Amazing",
        url: "https://duckduckgo.com/?q=ud+amazing&ia=dictionary"
    },
    ...
]

This appears as:

ud infobox

InfoBox Nested Properties

The value property of infoboxData objects can also be passed an array of objects. These objects have the following properties:

  • label [required] string
  • value [required] string

For example, the resulting array passed to infoboxData could be structured this way:

[
    {
        heading: "About Me"
    },
    {
        label: "My Favorites",
        value: [
            {
                label: "Color",
                value: "Red"
            },
            {
                label: "Animal",
                value: "Duck"
            },
            ...
        ]
    },
    ...
]

places_item Template

An item template which displays multiple location results on one map.

Clicking a places item both indicates its location on a map, as well as 'flips' the item to display more detailed information. The places_item template can conceptually be divided into its 'front' and 'back'.

Template Diagram

'Front'

DuckDuckGo search for "cafes near ann arbor"

+--------------------+


        image


+--------------------+
name
ratingImageURL *or* rating
reviews
+--------------------+

'Back'

This view is displayed when the 'front' is clicked, together with the map (below).

DuckDuckGo search for "cafes near ann arbor"

+--------------------+

name (url)

price

address_lines *or* address

phone

+--------------------+

Available Features

'Front' of each item:

  • image [optional] string url

    Path to image

  • name [required] string

  • title [optional] string

    Available only if image specified

  • ratingImageURL [optional] string url

  • rating [optional] float

    A positive float with one decimal point, up to 5.0 Available only if ratingImageURL is not specified

  • reviews [optional] integer

    The count of reviews Automatically formatted to include comma thousands separators

'Back' of each item: (displayed upon click)

  • name [required] string
  • url [required] string url

  • price [optional] integer

    Integer between 1 and 4; converted to a dollar-sign rating (such as '$' or '$$$$')

  • address_lines [optional] array

    An array of strings, one for each line

  • address [optional] string

    Available only if address_lines not specified Limited to 65 characters, truncated to whole words with an ellipsis

  • phone [optional] string

Map View

This view is displayed when the 'front' is clicked, together with the 'back' (above).

DuckDuckGo search for "cafes near ann arbor"

Example Usage

Template Groups

basic_flipping_item Template

This template is used to replace places_item on the front and back of the item tile, when using the Places template group. This template maintains the unique 'flip' behavior of places_item, but allows.

Template Diagram

'Front'

These properties are passed to the template inside a data_front object (e.g. data_front.title).

+--------------------+


    icon
    title, altsubtitle
    subtitle
    footer_content


+--------------------+

'Back'

This view is displayed when the 'front' is clicked, together with the map (below). These properties are passed to the template inside a data_back object (e.g. data_back.title).

+--------------------+


    icon
    title, altsubtitle
    subtitle
    footer_content


+--------------------+

Available Features

'Front' of each item:

These properties are passed to the template inside a data_front object (e.g. data_front.title).

  • icon [optional]
  • title [optional]
  • altsubtitle [optional]
  • subtitle [optional]
  • footer_content [optional] sub-template

'Back' of each item: (displayed upon click)

These properties are passed to the template inside a data_back object (e.g. data_back.title).

  • icon [optional]
  • title [optional]
  • altsubtitle [optional]
  • subtitle [optional]
  • footer_content [optional] sub-template

Interactions in the Places Template Group

When used with the Places template group, the behavior is similar to the default places_item: when the 'front' is clicked, the map displays, as does the 'back'.

Before click:

After click:

Example Usage

  • GetEvents: search for events in new york

    In get_events.js, the places template group is specified, and overrides the item template. 

      templates: {
      group: 'places',
      item: 'basic_flipping_item'
  }

    The normalize function returns the data for each side, contained within the data_front and data_back properties:

      return {
      data_front: {
          showPin: true,
          title: item.name,
          venue: item.venue,
          image: item.image_large_url,
          altSubtitle: formatSubtitleString(item),

          footer_content: Spice.get_events.foot_front,

          footLines: '4',
          titleClass: 'tile__title--3 tx--16 tx--bold mg--none',
          altSubClass: 'tx--13 tx-clr--grey'
      },
      data_back: {
          title: item.name,
          url: buildUrl(item.id),
          description: item.description ? DDG.strip_html(item.description) : 'No description available.',

          footer_content: Spice.get_events.foot_back,

          titleClass: 'tile__title--1 tx--16 tx--bold'
      },
      city: item.venue.city,
      place: item.venue.name,
      lat: item.venue.lat,
      lon: item.venue.lng
  };

Template Groups

base_flipping_item Template

This template is used to replace places_item with custom sub-templates for the front and back of the item tile. This template maintains the unique 'flip' behavior of places_item, while allowing full customization of both sides.

Use as a last resort because of the large amount of upfront work and ongoing maintenance involved with fully-custom html.

It's important to note that the community cannot accept submissions using this template unless they've received prior permission (by discussing with community leaders or staff on Slack or email). If you feel that other templates do not meet your needs, definitely talk to us. We'll work with you to find the best way to express your idea and avoid ongoing, manual maintenance for your Instant Answer.

Template Diagram

'Front'

+--------------------+



    front_content



+--------------------+

'Back'

This view is displayed when the 'front' is clicked, together with the map (below).

+--------------------+



    back_content



+--------------------+

Available Features

'Front' of each item:

'Back' of each item: (displayed upon click)

Map View

As with places_item, map view is displayed when the 'front' is clicked, as it displays the 'back'.

Example Usage

  • Parking Panda: search for parking in new york.

    In parking.js, the places template group is specified, and override the item template. Then the two custom sub-templates are specified under options.

      templates: {
      group: 'places',
      item: 'base_flipping_item',
      options: {
          front_content: Spice.parking.item_front,
          back_content: Spice.parking.item_back
      }
  }

Template Groups

places_detail Template

A detail template for displaying information about a single location on a map backdrop.

Template Diagram

DuckDuckGo search for "espresso italiano maui"

+--------------------------------+------------+
|   name (url)                   |            |
|                                | image (url)|
|   ratingImageURL *or* rating   |            |
|   reviews                      |            |
|   price                        |            |
|   address_lines *or* address   |            |
|   phone                        |            |
|                                |            |
|                                |            |
+--------------------------------+            |
|                                |            |
|    hours                       |            |
|                                |            |
+--------------------------------+------------+

Available Features

  • url [required] string url
  • name [required] string

  • image [optional] string url

    URL path to image

  • title [optional]

    Used at alt attribute of the image element

  • hours [optional] array

    Array of objects, each containing day and hours properties

  • ratingImageURL [optional]

  • rating [optional] float

    A positive float with one decimal point, up to 5.0 Available only if ratingImageURL not specified

  • reviews [optional] integer

    The count of reviews Automatically formatted to include comma thousands separators

  • price [optional] integer

    Integer between 1 and 4; converted to a dollar-sign rating (such as '$' or '$$$$')- address_lines [optional] array

    An array of strings, one for each line

  • address [optional] string

    Available only if address_lines not specified

  • phone [optional] string

Example Usage

Template Groups

list_detail Template

A detail template for displaying of a title and subtitle above a bulleted list, or a table of key-value pairs.

Template Diagram

DuckDuckGo search for "whois mozilla.org"

+-------------------+

title
subtitle

content, record_data
*or*
list_content, list

+-------------------+

Available Features

  • title [optional] string
  • subtitle [optional] string or string array

If Displaying Table of Key-Value Pairs:

  • content [required] sub-template

    Recommended to set this value to 'record' (a string) to specify the built-in record sub-template. Learn more about built-in sub-templates.

  • record_data [required] object

    Includes the key-value pairs to display

If Displaying Bulleted List of Values:

  • list_content [required] sub-template

    Supply a custom handlebars sub-template. The sub-template will be rendered, enclosed by a li element. Learn more about sub-templates.

  • list array

    Array of objects, each contains the properties used by list_content sub-template

Usage

To display a bulleted list, pass a sub-template to the list_content property. To display a table of key-value pairs, pass the record template to the content property.

When displaying a bulleted list, the simplest case would be to pass list an array of objects like {value: 'foo'} and specify list_content to be a sub-template which only reads {{value}}.

Example Usage

Template Groups

record Template

A special template that is ideal for key-value data. It generates a <table> where each row contains a key and value. Often used as a sub-template, for example by the list_detail template.

Template Diagram

record template

+---------------------------------------------+
*key*           *value*
*key*           *value*     (of record_data)
*key*           *value*
...
+---------------------------------------------+

Available Features

  • record_data [required] object

    Contains key-value pairs to display in table format Values limited to 350 characters, truncated to whole words with an ellipsis

Usage

This template requires that a record_data property, which should contain the key-value data to be displayed. All the properties of the record_data object will be used as the keys for the table.

However, if you want to specify exactly which properties of the record_data object should be displayed, you can define an optional record_keys property. This is an array of strings, specifying which key-value pairs of record_data will be included.

An optional property called rowHighlight can be added to options to turn on alternating row highlighting.

Sample Code

data: {
    record_data: {
        name: 'Bob',
        phone: '123-456-7890',
        email: '[email protected]',
        address: '123 First Street'
    }
},
normalize: function(item){
    return {
        record_keys: ["name", "phone", "email"]
    }
},
templates: {
    group: 'base',
    options: {
        content: 'record',
        /* optional - highlight alternate rows */
        rowHighlight: true
    }
}

Example Usage

Template Groups

  • Can be used as a sub-template by the List template group (under the list_detail template)

media_item Template

Template Diagram

+----------------------+

        image


title
altSubtitle
subtitle
description

footer        dateBadge   

+----------------------+

Available Features

  • title [required] string
  • altSubtitle [optional] string or string array
  • subtitle [optional] string or string array
  • description [optional] string
  • footer [optional] sub-template

  • dateBadge [optional] object

    An object with either a text string property or a month string and day string properties. For an example of a dateBadge in action, search for "concert in toronto" and see the SeatGeek Events by City Spice. (The example uses the text_item template, but the dateBadge is the same.)

Example Usage

Template Groups

media_item_detail Template

Template Diagram

+------------------------------------------------------------------+
                        title, altSubtitle
    image                subtitle
                        description
                        callout
+------------------------------------------------------------------+

Available Features

  • image [optional] string url
  • title [required] string
  • altSubtitle [optional] string or string array
  • description [optional] string

  • callout [optional] sub-template

    Can be used to provide a call-to-action, such as a button.

Example Usage

Template Groups

images_item Template

Template Diagram

Regular State

+-------------------+

    thumbnail

+-------------------+

Hover State

+-------------------+

   width × height

+-------------------+

Available Features

  • thumbnail [required] string url

  • tileWidth [required] integer

    The pixel width of the thumbnail image - may vary among tiles

  • title [optional] string

    The alt html attribute of the image element

  • width [required] integer

    The pixel width of the original image.

  • height [required] integer

    The pixel height of the original image.

Example Usage

Template Groups

images_detail Template

Template Diagram

+------------------------------------------------------------------+


    thumbnail                   title
    or                          url
    highResImage                width × height
                                image

+------------------------------------------------------------------+

Available Features

  • thumbnail [required] string url
  • highResImage [optional] string url
  • title [required] string

  • url [required] string url

    Path to image source page (the page on which the image was originally embedded)

  • width [required] integer

    The pixel width of the original image.

  • height [required] integer

    The pixel height of the original image.

  • image [required] string url

    Path to image source file (the original image file path)

Example Usage

  • Search for "duck images" and click on any item (built-in images Instant Answer)

Template Groups

videos_item Template

Template Diagram

+----------------------+

    images.medium

    duration


    title
    viewCount

+----------------------+

Available Features

  • images [required] object

    Object with paths to various image sizes. This template requires a medium property.

  • duration [required] string url

    Duration of the video, in HH:MM:SS format (e.g. '5:32' or '2:01:59')

  • title [required] string

  • viewCount [required] string

    Number of video views, preferably with commas as the thousands separator (value not formatted automatically)

Example Usage

Template Groups

videos_detail Template

Template Diagram

+------------------------------------------------------------------+


    [video content]             title
                                username
                                viewCount
                                published

+------------------------------------------------------------------+

Available Features

  • title [required] string
  • url [required] string url
  • username [required] string
  • viewCount [required] string

  • published [required] string

    A date string in any format recognized by the JavaScript Date.parse() method

Example Usage

  • "gopro videos" and click on any item (built-in videos Instant Answer)

Template Groups

base_item Template

An item template for containing fully customized markup.

Use as a last resort because of the large amount of upfront work and ongoing maintenance involved.

It's important to note that the community cannot accept submissions using this template unless they've received prior permission (by discussing with community leaders or staff on Slack or email). If you feel that other templates do not meet your needs, definitely talk to us. We'll work with you to find the best way to express your idea and avoid ongoing, manual maintenance for your Instant Answer.

Template Diagram

base_item template

+---------------------------------+


        content (template)


+---------------------------------+

Available Features

Example Usage

Complex Example

Here is an example of a more complex content sub-template passed to the base_item template.

base_item template (complex example)

Template Groups

base_detail Template

A detail template for containing fully customized markup.

Use as a last resort because of the large amount of upfront work and ongoing maintenance involved.

It's important to note that the community cannot accept submissions using this template unless they've received prior permission (by discussing with community leaders or staff on Slack or email). If you feel that other templates do not meet your needs, definitely talk to us. We'll work with you to find the best way to express your idea and avoid ongoing, manual maintenance for your Instant Answer.

Template Diagram

base_detail template

+---------------------------------+


        content (template)


+---------------------------------+

Available Features

Example Usage

Complex Example

base_detail template (complex example)

Template Groups