Template groups are preset properties for template and its options that work well together. In most cases at least one group will be a good fit for your Instant Answer.
We strongly recommend using a template group in your Instant Answer. Of course, if you cannot use an available template for your Instant Answer, definitely let us know. E-mail us at open@duckduckgo.com and we'll help you. We may find that a custom template is necessary, and we'll work with you to create an awesome one. (Who knows, your idea may inspire the next official template group!)
Setting a template group automatically sets the item and detail templates for you. Some template groups also set an item_detail template and a few default options.
You can easily customize the appearance of the template group by overriding the default options in your Instant Answer front end code. The appearance will also be affected by which data is returned with each item.
The best template group for your Instant Answer depends on what your Instant Answer is returning. Below are a few suggestions to help you narrow down your options.
A quick way to get a feel for the different template groups is to browse the Instant Answer directory. You can filter by the template group used on the right of the page.
The Media template group works well when an image is a significant part of the display of an item, as might be a title and a rating. Also consider the Movies template group.
Examples that make a great fit for the Media or Movies template groups include:
If your Instant Answer results are themselves images or videos, consider the Images or Videos template groups.
The Info template group is designed for Instant Answers that feature in-depth information about one item. It also provides an auxiliary section to display further detail in table or list format.
Examples include:
The List template group works well for lookups that don't need an image; this group is excellent for displaying attributes in just a list or table format. Take a look at the following example:
The Text and Icon template groups are simple templates for presenting text results. They both share the same item template, while the Icon group's detail template is better suited to displaying an icon image.
These results fit this format well:
The Products template group is great for items characterized by a price, brand, and rating. This is a good template group where images are important.
Examples of results that work well with the Products template group include:
The Places template group is perfect for results where location is an important aspect. This template group displays single and multiple items on a map.
Results that would make a good fit for the Places template group include:
- Parking
- Local businesses
- Hiking trails
- Historical sites
- Surf spots
- Shark GPS locations
We encourage you to think hard about using an existing template group. For example, many detail templates accept custom handlebars sub-templates. Additionally, many template features can be toggled.
If working within existing template groups feels too constraining, we're happy to help you figure out how your vision could be accomplished using existing templates. E-mail us at open@duckduckgo.com and we'll work with you to find the best way to express your idea.
In this context, the Base template group is a minimal container template that accepts totally custom markup. Because of this, the Base template group is a complete last-resort because of the amount of work up front, and difficult maintenance over time.
Please hold off from using the Base template group until you've contacted us. We hope to save you from ongoing, manual maintenance of your Instant Answer display. Additionally, knowing where our templates fall short helps us understand where we can improve our existing set of templates.
This reference explains what each template group looks like, how it works, and what content works fits it best. Each template group is accompanied by live examples, layout diagrams, code links, and available features.
These are the currently available template groups:
When no options are specified and no template group has been selected, the options are implicitly set as follows:
options: {
price: true,
brand: true,
priceAndBrand: true,
rating: true,
ratingText: true,
moreAt: true,
content: false
}-
Before using these templates in your code, please familiarize yourself with the method for displaying your Instant Answer type (for example, Spice Display or Goodie Display). This will help understand the proper usage of both the
templatesblock and theoptionsblock. -
For your desired template features to display correctly, each item's data must contain the corresponding properties. Generally these are set with the aid of a
normalizefunction, if they do not already exist in yourdataobject.
Understanding these is crucial to implementing templates properly and effectively.
This template group is best used for results which are mostly text, where any images are icons or small logos. This template offers a title, description and footer.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'text'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'text'
// does this for you!
templates: {
item: 'text_item',
detail: 'text_detail'
}See the important notes for making this template display correctly.
The info template group is designed for Instant Answers that feature in-depth information about one item. This includes an image, title, and a description or arbitrary content. It also provides an auxiliary section to display further detail in table or list format (to the right).
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'info'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'info'
// does this for you!
templates: {
item: 'basic_image_item',
detail: 'basic_info_detail',
options: {
moreAt: true,
aux: false
}
}See the important notes for making this template display correctly.
Best used to showcase products with an image, rating, review, brand and/or price. An optional buy sub-template can be used to provide a compelling call-to-action (i.e. button).
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'products'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'products'
// does this for you!
templates: {
item: 'products_item',
detail: 'products_detail',
item_detail: 'products_item_detail',
wrap_detail: 'base_detail',
options: {
rating: true,
price: true,
brand: true
}
}Using the Products template group also automatically makes the Product model available.
See the important notes for making this template display correctly.
The media template group works well when an image is a significant part of the display of an item. Items can also have a title and a rating.
The item template is essentially a simplified version of the Products template group. It also uses the same detail template as the Products template group.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'media'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'media'
// does this for you!
templates: {
item: 'media_item',
detail: 'basic_info_detail',
item_detail: 'media_item_detail',
options: {
moreAt: true,
aux: false
}
}See the important notes for making this template display correctly.
This template is similar to the text group, since it uses the same item template. However, the detail view is better suited to displaying an icon image.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'icon'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'icon'
// does this for you!
templates: {
item: 'text_item',
detail: 'basic_icon_detail',
item_detail: 'products_item_detail'
}See the important notes for making this template display correctly.
A template group for displaying image results. This group is ideal when the Instant Answer result is an image, and the image's attributes are important (such as its dimensions, source, and original file).
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'images'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'images'
// does this for you!
templates: {
item: 'images_item',
detail: 'images_detail'
}Using the Images template group also automatically makes the Image model available.
- "duck images" (built-in images search)
An ideal template group for displaying movie results, but also great for other types of media such as books.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'movies'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'movies'
// does this for you!
templates: {
item: 'basic_image_item',
detail: 'products_detail',
item_detail: 'products_item_detail',
wrap_detail: 'base_detail',
options: {
price: false,
brand: false,
rating: false,
ratingText: true
},
variants: {
tile: 'poster'
},
elClass: {
tileBody: 'is-hidden'
}
}- "dogobooks harry potter" (code)
- "movies with keira knightley" (code)
- "jiro dreams of sushi rotten tomatoes"(code)
A template group for displaying online video results. This group is ideal when the Instant Answer result is a video, and can be viewed on the search results page.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'videos'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'videos'
// does this for you!
templates: {
item: 'videos_item',
detail: 'videos_detail'
}Setting the Videos template group also automatically makes the Video model available.
- "gopro videos" (built-in videos search)
This template group is ideal for displaying results where location is an important factor to the searcher. The Places template group makes it easy for searchers to view a map showing all results, or highlighting a particular item without leaving the search page.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'places'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'places'
// does this for you!
templates: {
item: 'places_item',
detail: 'places_detail'
}Using the Places template group also automatically makes the Place model available.
Specify these item templates to replace the default places_item template, while maintaining the unique 'flip' behavior of places_item.
The Places template group works together with the Places model and Places view. The Places model and view enable special map functionality and behaviors that make Instant Answers using Places valuable and delightful.
The model and view are specified alongside the template group property in your Instant Answer display options.
To work correctly, the places model requires additional values passed that do not appear directly in the templates. Make sure that each item includes the attributes required by the places model. Generally these are set by your normalize function if they do not already exist in your api_result.
The available attributes for the Places Model are:
idstring Unique identifier for the locationnamestring Name of the locationaddressstring Display address of the locationcitystringneighborhoodstring If neighborhood and city are both passed in, it will use neighborhood for the tile and fall back to the city when it's not thereimagestring Path to image thumbnail to be used for the location, will use default marker image if none is providedpolygonPointsarray If the location represents a region, array of lat/lon coordinates that create the shaded outline in queries like 'Paris map'latnumber Latitude of the locationlonnumber Longitude of the locationratingnumber Number from [0-5], supports half's, i.e.3.5ratingImageURLstring Optional, use custom rating image URL (i.e. Yelp)reviewsnumber Number of reviewspricenumber Integer from [0-4], will be converted to up to four$symbols, for example$$$$hoursobject Hash where three-char days are the keys and the values are a string of hours for that day, i.e.:{ 'Mon': '8am - 5pm', 'Thu': '1pm - 5pm' }phonestring
Below are examples of the objects passed to the data property in your Instant Answer display options (in this case, Spice.add()). These might be directly found in your api_result or created by defining a normalize function.
Spice.add({
id: 'landmarks',
name: 'Landmarks',
model: 'Place',
view: 'Map',
templates: {
group: 'places'
},
meta: {
sourceName: 'Wikipedia',
sourceUrl: 'https://wikipedia.org'
},
data: [
{
id: 'uniqueid-1',
name: 'Empire State Building',
url: 'https://en.wikipedia.org/wiki/Empire_State_Building',
image: 'https://upload.wikimedia.org/...480px-Empire_State_Building_by_David_Shankbone.jpg',
rating: '3.5',
address: '350 Fifth Ave',
neighborhood: 'Midtown',
city: 'New York City',
price: 3,
lat: 40.7484324,
lon: -73.98566413,
hours: {
Thu: '8am - 5pm'
}
}
]
});Example of rendering multiple locations as tiles with an expandable map:
Spice.add({
id: 'landmarks',
name: 'Landmarks',
model: 'Place',
view: 'Places',
templates: {
group: 'places'
},
meta: {
type: 'Landmarks',
sourceName: 'Wikipedia',
sourceUrl: 'https://wikipedia.org'
},
data: [
{
id: 'uniqueid-1',
name: 'Empire State Building',
url: 'https://en.wikipedia.org/wiki/Empire_State_Building',
image: 'https://upload.wikimedia.org/...480px-Empire_State_Building_by_David_Shankbone.jpg',
rating: '3.5',
address: '350 Fifth Ave',
neighborhood: 'Midtown',
city: 'New York City',
price: 3,
lat: 40.7484324,
lon: -73.98566413,
hours: {
Thu: '8am - 5pm'
}
},
{
id: 'uniqueid-2',
name: 'Central Park',
url: 'https://en.wikipedia.org/wiki/Central_Park',
image: 'https://upload.wikimedia.org/...240px-Southwest_corner_of_Central_Park%2C_looking_east%2C_NYC.jpg',
rating: 5,
address: '86th Street, Traverse Road',
neighborhood: 'Midtown',
city: 'New York City',
lat: "40.78257765",
lon: "-73.9654435614027",
phone: '867-5309',
reviews: 327,
polygonPoints: [
["-73.9812971", "40.7685782"],
["-73.9812422", "40.7686381"],
["-73.9808211", "40.7692536"],
...
["-73.9810729", "40.7683834"],
["-73.9811234", "40.7684477"],
["-73.9811992", "40.7685112"],
["-73.9812971", "40.7685782"]
]
}
]
});
The List template group was designed for displaying in-depth attributes of one item. These attributes can be displayed as either a bulleted list of properties, or a table of key-value pairs.
Multiple items are displayed using the same text_item template used by Text and Icon template groups. As a result, this template group is mainly useful for Instant Answers designed to return a single item with detailed properties.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'list'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'list'
// does this for you!
templates: {
item: 'text_item',
detail: 'list_detail'
}See the important notes for making this template display correctly.
This is the most rudimentary template group. It provides a minimal container template that accepts totally custom markup.
Using this template group requires a large amount of work up front, and difficult maintenance over time. As a result, this template should be a last resort.
It's important to note that the community cannot accept submissions using the Base template unless they've received prior permission (by discussing with community leaders or staff on [Slack]({{ book.slackURL }}) or email). If you feel that other template groups 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.
Using this template requires that that you set the group property of the templates block like so:
templates: {
group: 'base'
}When you specify this template group, it is equivalent to setting the properties of the templates block as follows:
// setting the template group to: 'base'
// does this for you!
templates: {
item: 'base_item',
detail: 'base_detail',
options: {
price: false,
brand: false,
rating: false,
ratingText: false,
rowHighlight: false,
keySpacing: false,
moreAt: false
}
}See the important notes for making this template display correctly.
